home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
CWL2A_2.ARJ
/
MANUAL.DOC
Wrap
Text File
|
1991-11-12
|
605KB
|
18,755 lines
THE C WINDOW LIBRARY
(c) Copyright P. A. McKenzie 1990, 1991
All Rights Reserved
Version 2.0
T A B L E O F C O N T E N T S
INTRODUCTION ....................................................... 1
Defining Windows ................................................ 1
Properties of Windows ........................................... 1
Writing to Overlapping Windows .................................. 1
Window Ranks .................................................... 2
Detection of Video Hardware ..................................... 2
Window Coordinates .............................................. 2
Video Attributes ................................................ 3
Direct Screen Writes and BIOS Screen Updates .................... 4
Video Paging .................................................... 5
Error Codes ..................................................... 6
Window Manager .................................................. 7
MANDATORY FUNCTIONS AND HEADER FILES ............................... 8
WindowInitializeSystem() ........................................ 8
CREATING WINDOWS ................................................... 9
The WINDOW structure and WPOINTER structure pointer ............. 9
WindowSaveInitial() ............................................. 9
WindowInitialize() .............................................. 10
CREATE_VIDEO_ATTRIBUTE() macro .................................. 11
Box types ....................................................... 11
OPENING WINDOWS FOR READING AND WRITING ............................ 13
WindowOpen() .................................................... 13
DISPLAYING WINDOWS ................................................. 14
The WindowDisplay() function and Explosion Effects .............. 14
Displaying Multiple Windows ..................................... 18
CLOSING WINDOWS .................................................... 20
WindowClose() ................................................... 20
WindowFree() .................................................... 22
WindowCloseAll() ................................................ 22
WindowFreeAll() ................................................. 23
CENTERING WINDOWS ON THE SCREEN .................................... 24
WindowCenter() .................................................. 24
CHANGING WINDOW CHARACTERISTICS .................................... 26
WindowChangeTextAttribute() ..................................... 26
WindowChangeBorderAttribute() ................................... 27
WindowDrawBorder() .............................................. 28
WindowRemoveBorder() ............................................ 29
WindowResizeHeight() ............................................ 29
WindowResizeWidth() ............................................. 30
Page i The C Window Library Page i
T A B L E O F C O N T E N T S
WRITING TEXT TO WINDOWS ............................................ 33
Null Terminated Write Functions ................................. 33
WindowWriteString() .......................................... 33
WindowWriteStringAttr() ...................................... 34
WindowWriteCenterString() .................................... 35
WindowWriteCenterStringAttr() ................................ 36
WindowWriteStringCC() ........................................ 36
WindowWriteStringCCAttr() .................................... 37
WindowWriteStringRJ() ........................................ 38
WindowWriteStringRJAttr() .................................... 39
Length Controlled Write Functions ............................... 40
WindowWriteCharacters() ...................................... 40
WindowWriteAttributes() ...................................... 41
WindowWriteCharAndAttr() ..................................... 42
WindowWriteCharactersAttr() .................................. 43
WindowWriteRepeatAttribute() ................................. 44
WindowWriteRepeatCharacter() ................................. 45
Formatted Write Functions ....................................... 46
Where output is placed in the window ......................... 46
WindowSetWrap() .............................................. 46
WindowPrintf() ............................................... 47
WindowPrintfAttr() ........................................... 48
WRITING TITLES TO WINDOWS .......................................... 49
WindowTitleTop() ................................................ 50
WindowTitleBottom() ............................................. 51
WindowTitleTopAttr() ............................................ 52
WindowTitleBottomAttr() ......................................... 53
READING CHARACTERS AND ATTRIBUTES FROM WINDOWS ..................... 55
WindowReadCharacters() .......................................... 55
WindowReadAttributes() .......................................... 56
WindowReadCharAndAttr() ......................................... 57
HIDING WINDOWS ..................................................... 59
WindowHide() .................................................... 59
CREATING COPIES OF A WINDOW ........................................ 61
WindowCopy() .................................................... 61
SCROLLING TEXT IN WINDOWS .......................................... 63
WindowScroll() .................................................. 63
WindowScrollRegion() ............................................ 64
WindowScrollAttr() .............................................. 65
WindowScrollRegionAttr() ........................................ 66
Page ii The C Window Library Page ii
T A B L E O F C O N T E N T S
CLEARING WINDOWS ................................................... 68
WindowClear() ................................................... 68
WindowClearAttr() ............................................... 69
WindowClearRegion() ............................................. 69
WindowClearRegionAttr() ......................................... 70
WRITING WINDOW CONTENTS TO A FILE .................................. 72
WindowWriteTextToFile() ......................................... 72
SHADOWING WINDOWS .................................................. 74
WindowDrawShadow() .............................................. 74
WindowRemoveShadow() ............................................ 76
SEE-THRU WINDOWS ................................................... 77
WindowMakeSeeThru() ............................................. 77
WindowMakeNormal() .............................................. 78
MOVING AND SLIDING WINDOWS ......................................... 79
WindowMove() .................................................... 79
WindowSlide() ................................................... 80
CURSOR POSITIONING IN WINDOWS ...................................... 81
Cursor Maintenance in The C Window Library ...................... 81
Creating Cursor Shapes .......................................... 81
WindowChangeCursor() ............................................ 81
WindowMoveCursor() .............................................. 82
WindowGetCursorShape() .......................................... 83
WindowGetCursorPosition() ....................................... 84
GETTING INPUT FROM WINDOWS ......................................... 86
Input Manager ................................................... 86
Regular Expressions ............................................. 86
Editing Input ................................................... 90
Last Key Value .................................................. 91
Default Cursor Types and Editing Mode ........................... 92
Editing using a character mask .................................. 93
Editing Functions ............................................... 93
WindowGetString() ............................................ 93
WindowGetStringAttr() ........................................ 96
WindowGetMaskString() ........................................ 97
WindowGetMaskStringAttr() .................................... 98
Getting Passwords ............................................ 99
WindowGetPassword() ....................................... 99
WindowGetPasswordAttr() ................................... 100
WindowGetMaskPassword() ................................... 101
WindowGetMaskPasswordAttr() ............................... 101
Page iii The C Window Library Page iii
T A B L E O F C O N T E N T S
UNDEFINED KEYSTROKE PROCESSING .................................. 104
The undef_fkey_func and undef_akey_func function pointers .... 104
Specifying when to call an undefined key function in a
Regular Expression ........................................ 105
Return Values To The Input Manager ........................ 105
INPUT OPTIONS ................................................... 108
CHECKREGEXP and the reg_exp_error_func function pointer ...... 109
THE num_chars_entered_func FUNCTION POINTER ..................... 112
OTHER INPUT RELATED FUNCTIONS ................................... 113
TranslateStringToMaskString() ................................ 113
TranslateMaskStringToString() ................................ 115
VIRTUAL WINDOWS .................................................... 116
Using Windows as Viewports ...................................... 116
Attributed and Non-Attributed Virtual Windows ................... 116
Virtual Window's Logical Cursor ................................. 117
CREATING VIRTUAL WINDOWS ........................................ 118
VirtualInitialize() .......................................... 118
ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS ....................... 120
WindowAssignToVirtual() ...................................... 120
Out of bounds Coordinates .................................... 121
WindowCloseViewport() ........................................ 122
WRITING TEXT TO VIRTUAL WINDOWS ................................. 124
Null Terminated String Functions ............................. 124
VirtualWriteString() ...................................... 124
VirtualWriteStringAttr() .................................. 125
VirtualWriteCenterString() ................................ 126
VirtualWriteCenterStringAttr() ............................ 127
VirtualWriteStringCC() .................................... 128
VirtualWriteStringCCAttr() ................................ 129
VirtualWriteStringRJ() .................................... 130
VirtualWriteStringRJAttr() ................................ 131
Length Controlled Functions .................................. 132
VirtualWriteCharacters() .................................. 132
VirtualWriteAttributes() .................................. 133
VirtualWriteCharAndAttr() ................................. 134
VirtualWriteRepeatAttribute() ............................. 135
VirtualWriteRepeatCharacter() ............................. 136
Formatted Write Functions .................................... 137
Format String ............................................. 137
Where Output is Placed .................................... 137
VirtualSetWrap() .......................................... 137
Page iv The C Window Library Page iv
T A B L E O F C O N T E N T S
VirtualPrintf() ........................................... 138
VirtualPrintfAttr() ....................................... 139
READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS .......... 140
VirtualReadCharacters() ...................................... 140
VirtualReadAttributes() ...................................... 141
VirtualReadCharAndAttr() ..................................... 142
REPOSITIONING THE VIEWPORT ...................................... 144
WindowPositionViewport() ..................................... 144
SCROLLING THE VIEWPORTS ......................................... 148
WindowScrollVirtual() ........................................ 148
WRITING VIRTUAL WINDOW CONTENTS TO A FILE ....................... 151
VirtualWriteTextToFile() ..................................... 151
MOVING THE LOGICAL CURSOR ....................................... 153
VirtualMoveCursor() .......................................... 153
VirtualGetCursorPosition() ................................... 153
CLEARING VIRTUAL WINDOWS ........................................ 155
VirtualClear() ............................................... 155
VirtualClearAttr() ........................................... 156
VirtualClearRegion() ......................................... 156
VirtualClearRegionAttr() ..................................... 157
FREEZING VIEWPORTS .............................................. 159
WindowFreeze() ............................................... 159
DISPOSING OF VIRTUAL WINDOWS .................................... 161
VirtualFree() ................................................ 161
INTRODUCTION TO MENU SYSTEM ........................................ 163
Menu Manager .................................................... 163
Necessary "include" files ....................................... 163
POP-UP MENUS .................................................... 164
Description .................................................. 164
Windows and Virtual Windows .................................. 164
Page v The C Window Library Page v
T A B L E O F C O N T E N T S
CREATING POP-UP MENUS ........................................... 165
The POPUP_MENU_ENTRY structure ............................... 165
Defining Hotkeys .......................................... 166
Assigning the function to perform ......................... 167
Coloring Popup Menus ......................................... 167
PopupCreateMenu() function ................................... 168
Popup Menu Options ........................................ 170
Default Popup Window and Creating Your own Windows ........ 172
Default Virtual Window and ................................ 173
Creating Your own Virtual Windows ......................... 173
Accessing Popup Windows and Virtual Windows ............... 173
Warnings .................................................. 174
Return Values for PopupCreateMenu() ....................... 174
SELECTING FROM POPUP MENUS ...................................... 176
PopupSelectMenu() function ................................... 176
Values passed to menu function ............................ 178
Values returned to menu manager ........................... 178
Return Values for PopupSelectMenu() ....................... 179
SETTING OPTIONS IN POPUP MENUS .................................. 180
The PopupSetOptions() function ............................... 180
Setting Multiple Options .................................. 181
Setting the PopupSetConfirmFunction() ..................... 181
Return Values for PopupSetOptions() function .............. 182
MAKING MENU ENTRIES AVAILABLE AND UNAVAILABLE ................... 183
PopupMakeEntryAvailable() and ................................ 183
PopupMakeEntryUnavailable() functions ........................ 183
POPUPOVERRIDE option ...................................... 183
Return Values for PopupMakeEntryAvaialble() and .............. 183
PopupMakeEntryUnavailable() functions ........................ 183
CHANGING THE MENU ENTRY STRINGS ................................. 185
PopupChangeEntryString() function ............................ 185
Return Values for PopupChangeEntryString() function .......... 185
REDEFINING MENU KEYS ............................................ 186
Setting Global Key Definitions and ........................... 186
the popup_key_definition Array ............................... 186
Setting Local Key Definitions ................................ 186
PopupAssignKeys() function ................................ 187
Return Values for PopupAssignKeys() function .............. 187
Page vi The C Window Library Page vi
T A B L E O F C O N T E N T S
PROCESSING UNDEFINED KEYS ....................................... 188
The popup_undef_key function pointer ......................... 188
Values returned to menu manager ........................... 188
PRE-INPUT FUNCTION .............................................. 191
Setting the global_popup_prefunc function pointer ............ 191
DISPOSING OF POPUP MENUS ........................................ 193
PopupMenuFree() .............................................. 193
Return Values for PopupMenuFree() ............................ 193
BAR MENUS .......................................................... 194
Description ..................................................... 194
Windows and Virtual Windows ..................................... 194
CREATING BAR MENUS .............................................. 195
The BAR_MENU_ENTRY structure ................................. 195
Defining Hotkeys .......................................... 196
Assigning the function to perform ......................... 197
Coloring Bar Menus ........................................... 197
BarCreateMenu() function ..................................... 198
Bar Menu Options .......................................... 200
Default Bar Menu Window and Creating Your own Windows ..... 201
Accessing bar menu windows ................................ 202
Warnings .................................................. 203
Return Values for BarCreateMenu() ......................... 203
SELECTING FROM BAR MENUS ........................................ 205
BarSelectMenu() function ..................................... 205
Values passed to menu function ............................ 206
Values returned to menu manager ........................... 207
Return Values for BarMenuSelect() ......................... 207
SETTING OPTIONS IN BAR MENUS .................................... 208
The BarSetOptions() function ................................. 208
Setting Multiple Options .................................. 209
Setting the BarSetConfirmFunction() ....................... 209
Return Values for BarSetOptions() function ................ 210
MAKING ENTRIES AVAILABLE AND UNAVAILABLE ........................ 211
BarMakeEntryAvailable() and .................................. 211
BarMakeEntryUnavailable() functions .......................... 211
BAROVERRIDE option ........................................ 211
Return Values for BarMakeEntryAvaialble() and ................ 211
BarMakeEntryUnavailable() functions .......................... 211
Page vii The C Window Library Page vii
T A B L E O F C O N T E N T S
CHANGING THE MENU OPTIONS STRING ................................ 212
BarChangeEntryString() function .............................. 212
Return Values for BarChangeEntryString() function ......... 212
REDEFINING THE MENU KEYS ........................................ 213
Setting Global Key Definitions and ........................... 213
the bar_key_definition Array ................................. 213
Setting Local Key Definitions ................................ 213
BarAssignKeys() function .................................. 213
Return Values for BarAssignKeys() function ................ 214
PROCESSING UNDEFINED KEYS ....................................... 215
The bar_undef_key function pointer ........................... 215
Values returned to menu manager ........................... 215
PRE-INPUT FUNCTION .............................................. 218
Setting the global_bar_prefunc function pointer .............. 218
DISPOSING OF BAR MENUS .......................................... 220
BarMenuFree() function ....................................... 220
Return Values for BarMenuFree() .............................. 220
PULLDOWN MENUS ..................................................... 221
Description ..................................................... 221
Bar Menu and Popup Menu levels .................................. 221
CREATING PULLDOWN MENUS ......................................... 222
The PulldownCreateMenu() function ............................ 223
Automatic Adjustment of Popup Windows ..................... 225
Return values for PulldownCreateMenu() ....................... 227
SELECTING FROM PULLDOWN MENUS ................................... 228
The PulldownSelectMenu() function ............................ 228
Immediate Mode ............................................ 228
Values passed to the selected menu function ............... 229
Values returned to the menu manager ....................... 229
Return Values for PulldownSelectMenu() .................... 229
REDEFINING KEY DEFINITIONS ...................................... 230
REDEFINING KEY DEFINITIONS FOR POPUP MENUS ................... 231
Setting Popup Menu Global Key Definitions ................. 231
Setting Popup Menu Local Definitions ...................... 231
Page viii The C Window Library Page viii
T A B L E O F C O N T E N T S
REDEFINING KEY DEFINITIONS FOR THE BAR MENU .................. 233
Setting bar menu global key definitions ................... 233
Setting Bar Menu Local definitions ........................ 233
PROCESSING UNDEFINED POPUP MENU KEYS ............................ 234
PROCESSING UNDEFINED BAR MENU KEYS .............................. 235
DISPOSING OF PULLDOWN MENUS ..................................... 236
The PulldownMenuFree() function .............................. 236
The PulldownMenuFreeAll() function ........................... 236
SUMMARY OF PULLDOWN MENUS ....................................... 237
EXAMPLE OF PULLDOWN MENU SYSTEM ................................. 238
MISCELLANEOUS FUNCTIONS ............................................ 243
SETTING AND CHECKING VIDEO PAGES ................................ 243
CheckVideoPage() ............................................. 243
SetActiveVideoPage() function ................................ 244
SetVisibleVideoPage() function ............................... 245
GENERAL STRING WRITING FUNCTIONS ................................ 247
VideoWriteString() ........................................... 247
VideoWriteStringAttr() ....................................... 248
VideoWriteAttributes() ....................................... 248
VideoWriteCenterString() ..................................... 249
VideoWriteCenterStringAttr() ................................. 250
VideoWriteCharAndAttr() ...................................... 250
VideoWriteStringCC() ......................................... 251
VideoWriteStringCCAttr() ..................................... 252
VideoWriteStringRJ() ......................................... 252
VideoWriteStringRJAttr() ..................................... 253
VideoPrintf() ................................................ 254
VideoPrintfAttr() ............................................ 254
READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN ............... 255
VideoReadCharacters() ........................................ 255
VideoReadAttributes() ........................................ 255
VideoReadCharAndAttr() ....................................... 256
Page ix The C Window Library Page ix
T A B L E O F C O N T E N T S
DRAWING BOXES ................................................... 257
VideoDrawBox() ............................................... 257
VideoDrawBoxAttr() ........................................... 257
SAVING AND RESTORING SCREEN IMAGES .............................. 259
VideoSave() .................................................. 259
VideoMove() .................................................. 260
VideoRestore() ............................................... 260
VideoFree() .................................................. 261
CLEARING SCREENS ................................................ 262
ClearScreen() ................................................ 262
ClearRegion() ................................................ 262
SCROLLING SCREENS ............................................... 264
ScrollScreenUp() ............................................. 264
ScrollScreenDown() ........................................... 264
CHANGING THE VIDEO MODE ......................................... 266
SetVideoMode() ............................................... 266
CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN ........... 267
Changing rows ................................................ 267
AdjustScreenInfo() ........................................ 267
AdjustGlobalData() ........................................ 268
SetVideoRows() ............................................ 268
Changing columns ............................................. 271
40 column and 80 column modes ............................. 271
Modes higher than 80 columns .............................. 271
CURSOR MANIPULATION ............................................. 273
MoveCursor() ................................................. 273
ChangeCursor() ............................................... 273
GetCursorShape() ............................................. 274
GetCursorPosition() .......................................... 274
HideCursor() ................................................. 275
BlockCursor() ................................................ 275
ThinCursor() ................................................. 275
GETTING VIDEO INFORMATION ....................................... 277
VIDEO_CONFIG structure ....................................... 277
GetVideoBiosInfo() ........................................... 277
Page x The C Window Library Page x
T A B L E O F C O N T E N T S
TIMED DELAYS .................................................... 279
delay() ...................................................... 279
SOUND FUNCTIONS ................................................. 280
sound() and nosound() ........................................ 280
MakeSound() .................................................. 280
ERROR HANDLING .................................................. 282
The window_error_func function pointer ....................... 282
USING A MOUSE WITH THE C WINDOW LIBRARY ......................... 284
Installing the Mouse Library ................................. 284
Include Files ................................................ 284
Initializing the Mouse with MouseInitializeSystem() .......... 284
Turning off the mouse with MouseRestoreSystem() .............. 285
Using a mouse with popup menus ............................... 286
Using a mouse with bar menus ................................. 288
Using a mouse with pulldown menus ............................ 289
Changing the mouse defaults .................................. 294
WINDOW AND VIRTUAL WINDOW MACROS ................................ 295
MENU MACROS ..................................................... 298
Popup Menu Macros ............................................ 298
Bar Menu Macros .............................................. 299
Pulldown Menu Macros ......................................... 300
VIDEO MACROS .................................................... 301
BOX MACROS ...................................................... 304
EXPLOSION MACROS ................................................ 305
KEYBOARD MACROS ................................................. 306
Keyboard Idle Function ........................................ 307
Keyboard Intercept Function ................................... 308
CURSOR MACROS ................................................... 309
IMPORTANT GLOBAL VARIABLES ......................................... 310
Page xi The C Window Library Page xi
INTRODUCTION
------------
Defining Windows
----------------
A window is an area of the screen that is separate and independent from the
other areas of the screen. With windows, you can scroll, write text, delete
text, etc. in a defined section of the screen. An example of windows in
application programs are the resident memory utilities that pop up on the
screen when invoked, and restore the text to its original state when the
resident application is terminated. Sidekick is a good example of what you
can do with windows. As a matter of fact, most professional programs use
windows in some manner. Some applications use windows to make pulldown menus
i.e. the integrated environment in the Turbo languages and in Microsoft Quick
C's integrated environment. Other applications such as text editors and word
processors use windows to display and edit a files contents. With The C
Window Library, you can create professional looking application program easily
and without worrying about the tricky details of window management. At your
disposal are tools that can help you create pull-down menus, popup menus, bar
menus, and just fast output.
Properties of Windows
---------------------
Windows should have the following properties:
- more than one window can be displayed on the screen simultaneously.
- windows are allowed to overlap without disturbing the contents of
the windows underneath.
- a window that is under a pile of windows can be brought to the top.
- a window that is under a pile of windows can be written to without
interfering with other windows.
- windows can be disposed of when not needed, and erased from the screen.
When erased, the contents of the screen underneath the window is restored.
- windows can be written to at any time.
- the window application should automatically detect the type of video
hardware used.
- the window functions should return an error if something goes wrong.
Writing to Overlapping Windows
------------------------------
With The C Window Library, if a window does overlap another window, this
overlap will be displayed on the physical screen. The C Window Library
allows you to direct output to any window at any time. When output is
written to a window, the window contents are updated in memory, but only the
visible portions of the window will be updated on the screen.
Page 1 The C Window Library Page 1
Window Ranks
------------
The rank order of the windows on the screen will determine which window has
priority of the screen.
Windows with lower rank numbers overlap windows with higher rank numbers. The
lowest rank number is 1, and the highest is 254. If a new window is opened
with the same rank number as another previously opened window, the new window
takes over the rank position, and the previous window's rank is increased
by 1. If there is a window with the same rank as the previous window's new
rank, its rank is increased by 1 etc. When a window is closed, all windows
with a higher rank number are decreased by 1.
Detection of Video Hardware
---------------------------
With The C Window Library, automatic detection of the type of video hardware
is necessary. Since The C Window Library can write directly to screen memory,
the starting memory address of screen memory must be known. Depending on the
video adapter, the starting address of screen memory is different. For
monochrome systems, the starting address is different from a color system.
If the window routines think that they are writing to a color system instead
of a monochrome system, crazy things will probably happen. For most
adapters, The C Window Library will detect them and assign the starting
address of screen memory to a global variable, so there is no need to specify
the starting address yourself.
Window Coordinates
------------------
A position on the screen can be specified as a pair of numbers. These numbers
will denote the row and column of the desired position. Rows and columns are
numbered from 1 to the maximum row or column number. The upper left hand
corner of the screen would be at row 1, column 1. For simplicity, row y,
column x will be abbreviated as (y,x). The position (1,1) is called the home
position.
However, when specifying a position in a window, this position is numbered
relative to the window itself. No matter where a window resides on the
screen, the upper left position of the window is (1,1), the second row of the
window is row 2, the fourth column is column 4, etc. The window coordinates
are called window relative coordinates. There are some window functions that
require you to enter physical screen (absolute) coordinates, but for most
functions, a window relative position would be needed. For example:
Page 2 The C Window Library Page 2
-------------------------------------------------------------------
|(1,1) (80,1)|
| |
| Valid Absolute Screen Coordinates |
| For 80 x 25 Screen |
| |
| This window opened at absolute (12,15) |
| | |
| v |
| ----------------------- |
| |(1,1) (1,30)| |
| | | |
| | | |
| |(14,1) (14,30)| |
| ----------------------- |
|(1,25) (80,25)|
-------------------------------------------------------------------
Video Attributes
----------------
With The C Window Library, a window can have an assortment of colors for text
and background. Each character that is displayed on the screen has its
corresponding attribute byte. The attribute byte is an 8-bit quantity that
specifies a character's color, intensity, and blink status. The format of the
attribute byte is as follows:
7 6 5 4 3 2 1 0
--------------------------
|B | bground |I|fground |
|__|_________|_|_________|
The B is the blink bit and the I is the intensity bit. Bits 0 thru 2
is a color code for the foreground (text) color. Bits 4 thru 6 determine
the color code for the background (screen) color.
If the blink bit is 1, then the character will blink. If the intensity bit is
on, the character will appear brighter than usual. Some monitors cannot
display high intensity characters, so the intensity bit may not change the
characters brightness at all.
Here is a list of color values along with the color they represent:
Value Color Value Color
0 Black 8 Gray
1 Blue 9 Light blue
2 Green 10 Light green
Page 3 The C Window Library Page 3
3 Cyan 11 Light cyan
4 Red 12 Light red
5 Magenta 13 Light magenta
6 Brown 14 Yellow
7 White 15 Intense white
If the video system is a monochrome system, the color values specified above
will give unpredictable results if not used carefully. Monochrome systems
also have an underline mode, that color systems (unless if you program the
EGA or VGA adapters) cannot display. Upcoming is a list of color values
that should work on monochrome systems along with the type of display that
will be produced:
Display Background Foreground
No display 0 0
Underline 0 1
Normal Video 0 7
Reverse Video 7 0
When programming a monochrome system, you can change the values of the colors
not supported to black and white combinations supported on the monochrome
system. For example, you can change the light green color's value from 10 to
7. Now if light green is selected as a foreground color and the background
color is black, you will have a normal video display on a monochrome system.
Direct Screen Writes and BIOS Screen Updates
--------------------------------------------
By default, The C Window Library writes directly to screen memory. This
results in very fast screen output. If you have ever wondered how commercial
programs can display output so rapidly on the screen, direct screen writing
is the major reason. The disadvantage of writing directly to the screen is
that it is ill- behaved with programs like Microsoft Windows or Quarterdeck's
DesQView (although DesQView386 running on an 80386 machine is well behaved
with direct screen writes). Also on some color systems, the screen output is
so fast that the video display produces "snow" on the screen. However, The C
Window Library will automatically detect whether "snow" should be checked
when writing directly to the screen. The old IBM Color Graphics Adapters
suffer from this problem, but most other adapters including monochrome,
Hercules, EGA, VGA, and newer CGA's do not suffer from this problem. When
checking for snow, the screen writes are not as fast as when there is no snow
checking, but it is fast enough.
The other method of updating the screen is by making a call to the video
functions contained in the ROM BIOS. BIOS stands for Basic Input Output
System. The BIOS provides routines that are needed for the operation of the
computer. Some of these routines are video functions needed to write
characters and attributes, move the cursor, and scroll portions of the
screen. Using the BIOS instead of writing directly to screen memory results
Page 4 The C Window Library Page 4
in much slower screen updates, but will be compatible with programs like
Microsoft Windows and DesQView.
With The C Window Library, you are allowed to use either method.
Video Paging
------------
Since most video display adapters have enough memory to store more than one
screen of characters, these video adapters will support multiple video pages.
With multiple video pages, you can write to a hidden video page and then
display the entire video page instantaneously. The only adapter that does
not support video paging is the Monochrome Display Adapter (MDA). All
CGA's, EGA's and VGA's support multiple video pages. The maximum number
of pages a card will support is determined by the amount of RAM included in
the video board, and the maximum number of characters that can be displayed
on each page. A list of the maximum number of video pages in each mode for
each card is as follows:
BIOS Mode Max. #
Mode # Type Adapter of pages
---- ---- ------- --------
0,1 Text CGA, EGA, VGA 8
2,3 Text CGA, 4
EGA, VGA 8
7 Text MDA, Hercules 1
EGA, VGA 8
With The C Window Library, the video page displayed on the screen is called
the visible page. When creating a window, its page number is recorded.
When updating windows, the video page number where the window resides is
used to direct the output to the appropriate video page. There are also
functions in The C Window Library that allow you to switch video pages.
With these routines, you can create very sophisticated user interfaces.
If you are using a clone Hercules Monochrome adapter, you may have access to
more than one video page. The original Hercules card has only one page of
text memory. The problem of accessing the other pages in the clone cards is
that there is no universal way to determine how many pages that the card
has. If you are writing an application that targets a specific Hercules
clone card, and you want to take advantage of the multiple pages, you can
modify a global variable that contains the maximum number of available video
pages, as well as the array that contains the segment:offset of each video
page. Make sure you have the full documentation for the card, or know
off-hand the number of pages and their addresses.
Page 5 The C Window Library Page 5
Error Codes
-----------
With most of The C Window Library functions, window_error_code, which is a
global integer variable is set to an error number when a function cannot be
completed. Throughout this documentation, you are to assume that
window_error_code is set to any error condition that is documented for
each function. The window_error_code variable IS NOT reset when a function
has been completed successfully. A list of error codes is as follows:
Error Constant Error Code Definition
-------------- ---------- ----------
NO_HEAP_MEM -1 Not enough memory to allocate from
the heap.
BAD_DISPLAY_PAGE -2 Video Display page is invalid.
INVALID_VIDEO_MODE -3 Invalid video mode.
INVALID_ROWS -4 Invalid number of screen rows
specified.
BAD_WINDOW -100 Window does not exist.
BAD_WINDOW_SIZE -101 Window dimensions are invalid.
WINDOW_NOT_OPEN -102 Window not open for read/write.
WINDOW_BOUND -103 Coordinates specified for window are
out of bounds.
MAX_WINDOW -104 Maximum number of windows defined.
WINDOW_INV_PARAM -105 An invalid parameter was encountered
in the function call.
NO_INPUT_CHARS -106 Trying to input a field of 0
characters.
BAD_V_WINDOW -200 The virtual window does not exist.
END_V_WINDOW -201 Internally used by The C Window
Library.
V_WINDOW_BOUND -202 Coordinates specified for virtual
window are out of bounds.
MAX_V_WINDOW -203 Maximum number of virtual windows
defined.
Page 6 The C Window Library Page 6
NO_ATTRIB -204 Virtual window does not have
attributes.
FILE_NO_EXIST -300 File does not exist.
FILE_CANT_CLOSE -301 Cannot close file.
FILE_CANT_OPEN -302 Cannot open file.
MENU_ENTRY_INVALID -400 An invalid menu entry was specified.
Window Manager
--------------
The window manager is the code in The C Window Library that handles window
initialization, movement, coloring, and other functions that control window
management.
Page 7 The C Window Library Page 7
MANDATORY FUNCTIONS AND HEADER FILES
------------------------------------
The only mandatory function is WindowInitializeSystem(), explained below.
The window.h header file must be included in any module that will call
functions included in The C Window Library.
WindowInitializeSystem()
------------------------
This function MUST be called before any other function defined in The C
Window Library. This function also sets global variables, so it is also
mandatory to call WindowInitializeSystem() before accessing any global
variables defined by The C Window Library.
WindowInitializeSystem() detects the type of video display used, the number
of rows and columns that the screen currently displays, and initializes data
structures and global variables.
Example:
#include "window.h"
main()
{
WindowInitializeSystem(); /* Initialization function */
/* Now it is safe to use C Window Library functions and global
variables */
}
There is no return value for WindowInitializeSystem().
Page 8 The C Window Library Page 8
CREATING WINDOWS
----------------
We will now look how a window is created by defining a WINDOW, WPOINTER, and
using the WindowSaveInitial() and WindowInitialize() function.
The WINDOW structure and WPOINTER structure pointer
---------------------------------------------------
When a window is created, the upper left hand column and row, the width,
height, etc. must be recorded. It would be very tedious if for every
function call that acts on these windows we have to specify width, height,
upper left hand row, etc. as function parameters. The C Window Library
conveniently has a structure called WINDOW, and its corresponding pointer
called a WPOINTER to alleviate these problems.
When a window is created, its characteristics are stored in a WINDOW
structure, and most functions require that a pointer to this structure be
passed. This pointer is called a WPOINTER. By only referring to the
WPOINTER, argument lists to functions become much shorter.
WindowSaveInitial()
-------------------
The WindowSaveInitial() function saves the base screen as a window. This
MUST be called prior to creating any windows. Here is a prototype:
int WindowSaveInitial(int page)
The page argument is the video page of the base screen to save. If you are
creating windows that will be manipulated on video page 0, you must call
WindowSaveInitial() with 0 as the argument:
#include "window.h"
main()
{
WindowInitializeSystem(); /* Initialize global variables */
WindowSaveInitial(0); /* Save video page 0's base screen */
}
In most applications, the initial screen page is page 0. However, it is
safer to use the global variable active_video_page (explained in the
IMPORTANT GLOBAL VARIABLES section) to determine the page. If you are
changing video pages in an application, and the new page has not been
accessed, you should call WindowSaveInitial() for that page. It is important
to save the base screen before writing windows on the screen. If the base is
not saved, the window manager will not update the
Page 9 The C Window Library Page 9
screen properly when moving windows, hiding windows, etc. This function must
be called only once in an application for each screen page desired.
If there is no error, WindowSaveInitial() returns NO_ERROR.
If there is an error, WindowSaveInitial() returns the following values:
BAD_DISPLAY_PAGE if the page desired does not exist, or was not detected
by The C Window Library.
NO_HEAP_MEM if there is no memory to save the initial screen.
MAX_WINDOW if the maximum number of windows has already been defined.
WindowInitialize()
------------------
The next function is WindowInitialize(). This function sets up a window with
the position on the screen to place the window, width, height, colors,
and box type. If successful, this function returns a new WPOINTER. Here is
an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,15,NORM,NORM,SINGLEBOX);
...
}
In the above example, we have defined a variable w as having a WPOINTER type.
This variable will ultimately point to a valid WINDOW structure. The first
argument to WindowInitialize() is a constant called BORDER. This tells the
window manager that the window desired is going to have a border. If no
border was desired, the constant would be NOBORDER. The second and third
arguments tells the window manager the row and column of the screen where the
upper left corner of the window will be located. Since the upper left corner
of the screen is row 1, column 1, the upper left hand corner of the window
will be placed at the upper left corner of the video screen. The fourth and
fifth argument denotes the width and the height of the window. DO NOT
INCLUDE THE BORDERS (if any) TO DETERMINE THE WIDTH AND HEIGHT OF THE WINDOW.
Our window will have a width of 30 characters and a height of 15 characters.
The sixth and seventh arguments are the video attributes of the inside of the
window and the border respectively.
The last argument tells us what type of border the window will have. We use
the constant SINGLEBOX to tell the window manager that we want a window with
Page 10 The C Window Library Page 10
a border made up of single lines.
If there is no error, WindowInitialize() returns a valid WPOINTER.
If there is an error, WindowInitialize() returns a WIN_NULL_PTR (a null
window pointer) and sets window_error_code to one of the following values:
NO_HEAP_MEM if there is not enough memory to allocate for the window
structure.
BAD_WINDOW_SIZE if the dimensions for the window are too large for the
physical screen.
MAX_WINDOW if there are > 254 windows defined.
Even though there is a structure type called WINDOW, you should always use
the pointer to the structure (WPOINTER) rather than the WINDOW structure
itself.
CREATE_VIDEO_ATTRIBUTE() macro
------------------------------
Please note the use of the macro CREATE_VIDEO_ATTRIBUTE() in the previous
example to create an integer representing the foreground and background
colors. This macro uses the first argument as the background color, and the
second argument is the foreground color. In the above example we have a
constant called NORM which uses CREATE_VIDEO_ATTRIBUTE() to create a black
background and a white foreground color combination.
Box types
---------
For ease of use, There are predefined constants found in the vidsys.h
header file that contains definitions of common border types. These
constants are as follows:
DOUBLEBOX -- defines border characters for double box windows.
SINGLEBOX -- defines border characters for single box windows.
MIXEDBOX1 -- defines double lines for top and bottom and single lines on the
sides.
MIXEDBOX2 -- defines single lines for top and bottom and double lines on the
sides.
HATCHBOX1 -- defines a 'dotty' box.
HATCHBOX2 -- Another 'dotty' box.
Page 11 The C Window Library Page 11
HATCHBOX3 -- Yet another 'dotty' box.
SOLIDBOX1 -- defines a box of solid characters.
SOLIDBOX2 -- defines another box of different solid characters.
BLANKBOX -- defines a box with a blank border. When using these characters,
do not get confused with a window with no border, and a window
with a blank border.
DOTTEDLINE -- defines a box with dotted lines.
Although there are predefined border types in The C Window Library, you can
define your own types. The window border characters are represented by an 8
byte character string. Each character in this string refers to a border
character to be used in drawing the window border. A list of what each
position in the string stands for is as follows:
position Representation
-------- ---------------------------
0 Upper left corner character.
1 Top line character.
2 Upper right corner character.
3 Left side character.
4 Right side character.
5 Bottom left corner character.
6 Bottom line character.
7 Bottom right corner character.
This character string is sent to the window functions that call for a string
of box drawing characters. For example, you can create your own customized
set of characters with something like this:
#define MYBOXCHARS "+-+||+-+"
MYBOXCHARS is a literal string of box drawing characters. Using the rules of
box drawing characters defined above, the upper left hand corner of the box is
the plus sign, the top line is the hyphen, the upper right and corner is the
plus sign, the left side is a pipe character, as is the right side, and the
bottom part of the box is defined the same as the upper part. Then you would
use it in a call to any function that asks for a box drawing string like this
w = WindowInitialize(BORDER, ... ,MYBOXCHARS);
The '... ' are the other arguments that you would normally put for the
WindowInitialize() function.
Page 12 The C Window Library Page 12
OPENING WINDOWS FOR READING AND WRITING
---------------------------------------
The next step is to allocate memory for the window's text buffer. This will
allow writing and reading characters to the window even though it is not
visible.
WindowOpen()
------------
The WindowOpen() function is used to allocate memory for the window's text
buffer. This function MUST be called if you are going to do many of the
window functions. Here is the previous example with the WindowOpen() call:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,15,NORM,NORM,SINGLEBOX);
WindowOpen(w);
...
}
The WindowOpen() function does not display the window. The argument tells
the window manager what window to open. In this case we want to open our new
window, w. The window buffer is cleared to spaces using the window's text
attribute, and the border (if there is a border) is drawn internally. When a
window is opened with WindowOpen(), you can then write or read characters to
a window, move, scroll, etc. almost any function that you can do with a
visible window.
If there is no error, WindowOpen() returns NO_ERROR.
If there is an error, WindowOpen() returns one of the following:
1) NO_HEAP_MEM if there is not enough memory to allocate for the window
buffer.
2) BAD_WINDOW if the window does not exist.
Page 13 The C Window Library Page 13
DISPLAYING WINDOWS
------------------
Now we will display the window we created in the previous example.
The WindowDisplay() function and Explosion Effects
--------------------------------------------------
The WindowDisplay() function displays a window. Here is the previous
example with WindowDisplay() added to it:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,15,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
...
}
The first argument to WindowDisplay() is the window to display, in our case,
w is the window. The second argument is the rank order of the window.
Since the rank order we desire is 1, this window will lie on top of all
windows, unless another window is opened with a rank of 1. Remember, any
window with a rank number n will have windows with rank n-1, n-2,...,1 to be
displayed on top of it. You can change the rank order of a window at any
time by calling WindowDisplay() with a different rank number.
The third argument to WindowDisplay() is the explosion effect of the window
when it is displayed. There are currently 12 ways to explode a window on the
screen, numbered from 0 thru 11. Here is an overview of each effect:
Defined Constant Value Effect
---------------- ----- ------
NOEFFECT 0 ┌─────────────┐
│ │
│ │
│ │
│ │
│ │
│ │
│ │
└─────────────┘
Page 14 The C Window Library Page 14
EXPLODE 1 ┌─────────────────┐
│ ^ │
│ | │
│ | │
│<-- -->│
│ │
│ | │
│ | │
│ v │
└─────────────────┘
CONTRACT 2 ┌─────────────────┐
│ | │
│ | │
│ v │
│--> <--│
│ ^ │
│ | │
│ | │
└─────────────────┘
BRICKS 3 ┌────────────────┐
│█ █ █ █│
│ █ │
│ █ █ █ │
│ █ │
│ █ █ █ █ │
│█ █ │
└────────────────┘
^
MIDDLEROWOUT 4 |
┌───────────────┐
└───────────────┘
|
v
Page 15 The C Window Library Page 15
TOPBOTTOMIN 5 ┌───────────────┐
└───────────────┘
|
v
^
|
┌───────────────┐
└───────────────┘
TOPDOWN 6 ┌───────────────┐
└───────────────┘
|
v
^
BOTTOMUP 7 |
┌───────────────┐
└───────────────┘
MIDDLECOLOUT 8 ┌┐
││
││
││
<-││->
││
││
││
└┘
Page 16 The C Window Library Page 16
LEFTRIGHTIN 9 ┌┐ ┌┐
││ ││
││ ││
││ ││
││-> <-││
││ ││
││ ││
││ ││
││ ││
└┘ └┘
LEFTTORIGHT 10 ┌┐
││
││
││
││->
││
││
││
││
└┘
RIGHTTOLEFT 11 ┌┐
││
││
││
<-││
││
││
││
││
└┘
If there is no error, WindowDisplay() will return NO_ERROR.
If there is an error, WindowDisplay() will return one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open with WindowOpen().
Page 17 The C Window Library Page 17
Displaying Multiple Windows
---------------------------
If you are creating multiple windows you can change the rank of the window by
calling WindowDisplay() with a different rank number. Here is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white) /* define video
attribute */
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) /* define
video attribute */
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
main()
{
int i;
WPOINTER w1,w2,w3; /* pointers to a window structures */
WindowInitializeSystem(); /* system initialization function */
WindowSaveInitial(0);
w1 = WindowInitialize(BORDER, /* Window has a border */
1, /* row on the screen to open window */
1, /* column on screen to open window */
30, /* width in characters of the window */
15, /* height of characters in window */
BLUEONBLACK, /* video attribute of text area of window */
NORM, /* video attribute of border */
SINGLEBOX); /* type of border to draw */
/* define second window */
w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM,DOUBLEBOX);
/* define third window */
w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM,SINGLEBOX);
WindowOpen(w1); /* make window 1 ok to write */
WindowOpen(w2); /* make window 2 ok to write */
WindowOpen(w3); /* make window 3 ok to write */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
GET_KEY();
WindowDisplay(w2,1,NOEFFECT);
GET_KEY();
Page 18 The C Window Library Page 18
WindowDisplay(w3,1,NOEFFECT);
GET_KEY();
WindowDisplay(w1,1,NOEFFECT);
GET_KEY();
}
In the above program, w1, w2, and w3 are displayed with rank numbers of 1, 2,
and 3, respectively. The ordering means that w1 will overlay w2, and w2 will
overlay w3.
Note that after the windows w1, w2, and w3 are initially displayed, they are
redisplayed by making another call to WindowDisplay(). You can redisplay a
window and change its rank by calling the WindowDisplay() function again. For
example, w2 is redisplayed with a rank of 1. This promotes w2 to the top of
the stack of displayed windows, and demotes w1 with a rank of 2. Each and
every window has a unique rank number. The window manager keeps track of
conflicts in rank numbers, and adjusts the data structures involved in
maintaining the windows in working order. Therefore, there is really no need
for you to remember whether a rank number is used or not.
The macro GET_KEY() pauses the program until you press a key.
Page 19 The C Window Library Page 19
CLOSING WINDOWS
---------------
In this section, we will discuss closing windows with and without destroying
the window pointer.
WindowClose()
-------------
The WindowClose() function hides a window from the screen and deallocates any
memory that was allocated by the WindowOpen() function described in the
previous section. This DOES NOT destroy the window pointer (WPOINTER),
however you must call WindowOpen() again if you want to use this window again
for most other window functions. Here is the prototype:
int WindowClose(WPOINTER w, int effect)
The first argument is the window. The second argument is the special effect
to use when closing the window. This argument is only meaningful if the
window is visible. For a list of effects refer back to the DISPLAYING
WINDOWS section. This function can be used if you are short of memory, but
you do not want to destroy the WPOINTER.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white) /* define video
attribute */
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) /* define
video attribute */
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
main()
{
int i;
WPOINTER w1,w2,w3; /* pointers to a window structures */
WindowInitializeSystem(); /* system initialization function */
WindowSaveInitial(0);
w1 = WindowInitialize(BORDER, /* Window has a border */
1, /* row on the screen to open window */
1, /* column on screen to open window */
30, /* width in characters of the window */
15, /* height of characters in window */
BLUEONBLACK, /* video attribute of text area of window */
NORM, /* video attribute of border */
Page 20 The C Window Library Page 20
SINGLEBOX); /* type of border to draw */
/* define second window */
w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM,DOUBLEBOX);
/* define third window */
w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM,SINGLEBOX);
WindowOpen(w1); /* make window 1 ok to write */
WindowOpen(w2); /* make window 2 ok to write */
WindowOpen(w3); /* make window 3 ok to write */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
GET_KEY();
WindowDisplay(w2,1,NOEFFECT);
GET_KEY();
WindowDisplay(w3,1,NOEFFECT);
GET_KEY();
WindowDisplay(w1,1,NOEFFECT);
GET_KEY();
WindowClose(w2,NOEFFECT);
GET_KEY();
WindowClose(w3,NOEFFECT);
GET_KEY();
WindowClose(w1,NOEFFECT);
}
The example above calls WindowClose() on all three windows.
If there are no errors, WindowClose() returns NO_ERROR.
If there are errors, WindowClose() returns the following value:
BAD_WINDOW if the window w does not exist.
Page 21 The C Window Library Page 21
WindowFree()
------------
The WindowFree() function acts just like the WindowClose() function except
that the WPOINTER is also deallocated. This means that the WPOINTER cannot
be used anymore unless it is initialized again using WindowInitialize(), or
is assigned to another valid WPOINTER. Here is the prototype:
int WindowFree(WPOINTER w, int effect)
Refer to WindowClose() for definitions of arguments and return values.
WindowCloseAll()
----------------
The WindowCloseAll() function acts just like WindowClose() function except
that all windows are closed on a desired video page. Here is the prototype:
int WindowCloseAll(int page, int effect)
The page argument is the video page of where the windows are located.
Remember that The C Window Library allows displaying windows on video pages
other than page 0 (default page). The effect argument is the special effect
to use when closing the window. Refer to DISPLAYING WINDOWS for the
list of special effects.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white) /* define video
attribute */
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) /* define
video attribute */
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
main()
{
int i;
WPOINTER w1,w2,w3; /* pointers to a window structures */
WindowInitializeSystem(); /* system initialization function */
WindowSaveInitial(0);
w1 = WindowInitialize(BORDER, /* Window has a border */
1, /* row on the screen to open window */
1, /* column on screen to open window */
30, /* width in characters of the window */
15, /* height of characters in window */
BLUEONBLACK, /* video attribute of text area of window */
Page 22 The C Window Library Page 22
NORM, /* video attribute of border */
SINGLEBOX); /* type of border to draw */
/* define second window */
w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM,DOUBLEBOX);
/* define third window */
w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM,SINGLEBOX);
WindowOpen(w1); /* make window 1 ok to write */
WindowOpen(w2); /* make window 2 ok to write */
WindowOpen(w3); /* make window 3 ok to write */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
WindowCloseAll(0,NOEFFECT); /* close all the windows */
}
The example above calls WindowCloseAll() to close all three windows.
Refer to WindowClose() for return values.
WindowFreeAll()
---------------
The WindowFreeAll() function acts just like WindowClose() function except
that all windows are freed on a desired video page. Here is the prototype:
int WindowFreeAll(int page, int effect)
The page argument is the video page of where the windows are located.
Remember that The C Window Library allows displaying windows on video pages
other than page 0 (default page). The effect argument is the special effect
to use when closing the window. Refer to DISPLAYING WINDOWS for the list of
special effects.
Refer to WindowCloseAll() for return values.
Page 23 The C Window Library Page 23
CENTERING WINDOWS ON THE SCREEN
-------------------------------
The C Window Library allows easy centering of windows on the screen.
WindowCenter()
______________
The WindowCenter() function centers a window on the screen vertically,
horizontally, or both. Here is the prototype:
int WindowCenter(WPOINTER w, int option)
The first argument is the window to center, and the second argument tells
whether to center the window horizontally, vertically, or both. The options
argument must be one of the following:
Value of
options Type of centering
------- -----------------
VERTCENTER vertical
HORIZCENTER horizontal
VERTCENTER | HORIZCENTER both horizontal and vertical
Note the bitwise OR (|) between the constants VERTCENTER and HORIZCENTER for
both horizontal and vertical centering. This function can be used on hidden
windows and windows that have not been opened with WindowOpen().
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
Page 24 The C Window Library Page 24
WindowCenter(w,VERTCENTER); /* center window vertically */
GET_KEY();
WindowMove(w,1,1);
GET_KEY();
WindowCenter(w,HORIZCENTER); /* center window horizontally */
GET_KEY();
WindowMove(w,1,1);
GET_KEY();
WindowCenter(w,VERTCENTER | HORIZCENTER); /* center both horizontal and
vertical */
GET_KEY();
WindowFree(w,NOEFFECT);
}
If there are no errors, WindowCenter() returns NO_ERROR.
If there is an error, the following value is returned:
BAD_WINDOW if the window does not exist.
Page 25 The C Window Library Page 25
CHANGING WINDOW CHARACTERISTICS
-------------------------------
In this section, we will discuss changing the window attributes, border
style, and the window's height and width.
WindowChangeTextAttribute()
---------------------------
This function changes the attribute of the text portion of the window. The
text portion is the inside of the window. Here is a prototype:
int WindowChangeTextAttribute(WPOINTER w, int color)
where w is the WPOINTER to change the text attribute, and color is the new
color. You can use the CREATE_VIDEO_ATTRIBUTE() macro to define the color.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowChangeTextAttribute(w,REVERSE);
}
If there is no error, WindowChangeTextAttribute() returns NO_ERROR.
If there is an error, the following value is returned:
BAD_WINDOW if the window does not exist.
Page 26 The C Window Library Page 26
WindowChangeBorderAttribute()
-----------------------------
This function changes the video attribute of the border of the window. If
the window does not have a border, nothing is changed. Here is a prototype:
int WindowChangeBorderAttribute(WPOINTER w, int color)
where w is the WPOINTER to change the border attribute, and color is the new
color. You can use the CREATE_VIDEO_ATTRIBUTE() macro to define the color.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowChangeBorderAttribute(w,REVERSE);
}
If there is no error, or if the window does not have a border,
WindowChangeBorderAttribute() returns NO_ERROR.
If there is an error, WindowChangeBorderAttribute() returns the following
value:
BAD_WINDOW if the WPOINTER w does not exist.
Page 27 The C Window Library Page 27
WindowDrawBorder()
------------------
You can also change the border type, or draw a border on an unbordered
window by calling the WindowDrawBorder() function.
Here is a prototype:
int WindowDrawBorder(WPOINTER w, char *box)
The first argument is the window we want to change the border of. The
second argument is a string of border characters. This string denotes the
type of border that the window should now have. In the example given below,
w is initialized with a SINGLEBOX border, but WindowDrawBorder() changes this
to a DOUBLEBOX.
The WindowDrawBorder() function is also used to draw borders on borderless
windows. When drawing borders on a NOBORDER window, the window must not have
any of its sides touching the edges of the physical screen. In other words,
the window must "have room" for a border to be drawn. If there is no room to
draw the border, there is no change to the window.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(NOBORDER,2,2,10,10,REVERSE,REVERSE,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowDrawBorder(w,DOUBLEBOX); /* Draws a double box around NOBORDER
window */
}
If there is no error, WindowDrawBorder() returns NO_ERROR.
If there is an error, WindowDrawBorder() returns one of the following values:
BAD_WINDOW if the window w does not exist.
NO_HEAP_MEM if there is not enough memory to allocate for temporary buffer.
Page 28 The C Window Library Page 28
WindowRemoveBorder()
--------------------
This function removes a border from a bordered window. Here is the
prototype:
int WindowRemoveBorder(WPOINTER w)
If the window does not have a border, nothing is changed.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,REVERSE,REVERSE,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowRemoveBorder(w); /* Removes the double box around BORDERed
window */
}
If there is no error, WindowRemoveBorder() returns NO_ERROR.
If there is an error, WindowRemoveBorder returns one of the following values:
BAD_WINDOW if the window w does not exist.
NO_HEAP_MEM if there is not enough memory to allocate for temporary buffer.
WindowResizeHeight()
--------------------
This function changes the inside (text portion) height of the window. Here
is a prototype:
int WindowResizeHeight(WPOINTER w, int newheight, int anchor)
The newheight argument is the new height of the window. If the height will
exceed the bounds of the screen, the window is given its maximum height. The
anchor argument determines which side to "hold down" while the window is
being resized. If the anchor is ANCHORTOP, the top line of the window is
held in its current position and the window is resized accordingly. If
anchor is ANCHORBOTTOM, the bottom of the window is held and the window is
resized accordingly.
Page 29 The C Window Library Page 29
If there is text in the window, the text will be truncated if the window is
made shorter (unless the window is a viewport to a virtual window. Virtual
windows are discussed in the VIRTUAL WINDOWS section).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowResizeHeight(w,15,ANCHORTOP); /* Resize the window with a new
height of 15 */
GET_KEY();
WindowResizeHeight(w,5,ANCHORBOTTOM); /* Resize window with new
height of 5 */
}
If there were no errors, NO_ERROR is returned.
If there is an error, WindowResizeHeight() returns one of the following
values:
BAD_WINDOW if the WPOINTER w does not exist.
NO_HEAP_MEM if there was not enough memory to allocate for the resized
window.
WindowResizeWidth()
-------------------
This function changes the inside (text portion) width of the window. Here
is a prototype:
int WindowResizeWidth(WPOINTER w, int newwidth, int anchor)
The newwidth argument is the new width of the window. If the width will
exceed the bounds of the screen, the window is given its maximum width. The
anchor argument determines which side to "hold down" while the window is
being resized. If the anchor is ANCHORLEFT, the left side of the window is
held in its current position and the window is resized accordingly. If
Page 30 The C Window Library Page 30
anchor is ANCHORRIGHT, the right side of the window is held and the window is
resized accordingly.
If there is text in the window, the text will be truncated if the window is
made shorter (unless the window is a viewport to a virtual window. Virtual
windows are discussed in the VIRTUAL WINDOWS section).
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowResizeWidth(w,15,ANCHORLEFT); /* Resize the window with a new
width of 15 */
GET_KEY();
WindowResizeWidth(w,5,ANCHORRIGHT); /* Resize window with new width
of 5 */
}
If there were no errors, NO_ERROR is returned.
If there is an error, WindowResizeWidth() returns one of the following:
BAD_WINDOW if the WPOINTER w does not exist.
NO_HEAP_MEM if there was not enough memory to allocate for the resized
window.
Page 31 The C Window Library Page 31
This page intentionally left blank
Page 32 The C Window Library Page 32
WRITING TEXT TO WINDOWS
-----------------------
There are various functions that will write text to a window. These
functions are divided into two groups: Functions that specify a null
terminated string, and functions that require the length of the string of
characters to write to be an explicit argument.
Null Terminated Write Functions
-------------------------------
WindowWriteString()
-------------------
The WindowWriteString() function writes a null terminated string of characters
to a window at a specified row and column of the window. If the string is too
long to fit in the boundaries of the window, the string is clipped (truncated)
to fit in the boundaries of the window.
Here is the prototype:
int WindowWriteString(WPOINTER w, char *string, int row, int col)
The first argument is the window to write the string to. The second argument
is the null terminated string to write. The third and fourth arguments are
the row and column of the window to place the string. The video attribute
used when writing the string is the video attribute of the inside of the
window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World",i,1);
}
Page 33 The C Window Library Page 33
The above example writes the string "Hello World" to each line of the window
w.
If there is no error WindowWriteString() returns NO_ERROR.
If there is an error WindowWriteString() returns the following:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_BOUND if the row or column specified are out of bounds of the window.
WINDOW_NOT_OPEN if the window was not open for writing (did not use
WindowOpen() on the window)
WindowWriteStringAttr()
-----------------------
The WindowWriteStringAttr() function works the same as the WindowWriteString()
function except that an extra argument determines the color used to write the
string. Here is the prototype:
int WindowWriteStringAttr(WPOINTER w, char *string, int row, int col,
int attr)
The first argument is the window to write the string to. The second argument
is the null terminated string to write. The third and fourth arguments are
the row and column of the window to place the string. The last argument is the
video attribute to use.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteStringAttr(w,"Hello World",i,1,REVERSE);
}
Page 34 The C Window Library Page 34
The above example writes the string "Hello World" to each line of the window
w using the video attribute defined by the constant REVERSE.
The return values to WindowWriteStringAttr() are the same as
WindowWriteString().
WindowWriteCenterString()
-------------------------
The WindowWriteCenterString() function centers a null terminated string in a
window. Here is a prototype:
int WindowWriteCenterString(WPOINTER w, char *string, int row)
The first argument is the window. The second argument is the string to write.
The third argument is the row that the string will be centered.
The attribute used to write the string is the attribute of the inside of the
window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteCenterString(w,"Hello World",i);
}
The above example writes and centers the string "Hello World" to each line of
the window w.
The return values for WindowWriteCenterString() are the same as
WindowWriteString().
Page 35 The C Window Library Page 35
WindowWriteCenterStringAttr()
-----------------------------
The WindowWriteCenterStringAttr() function works the same as the
WindowWriteCenterString() function except that an extra argument determines
the color used to write the string. Here is the prototype:
int WindowWriteCenterStringAttr(WPOINTER w, char *string, int row, int attr)
The first argument is the window. The second argument is the string to write.
The third argument is the row that the string will be centered. The last
argument is the video attribute to use to write the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
for (i=1;i<=10;i++)
WindowWriteCenterStringAttr(w,"Hello World",i,REVERSE);
}
The above example writes and centers the string "Hello World" to each line of
the window w using REVERSE as the video attribute.
The return values for WindowWriteCenterStringAttr() are the same as
WindowWriteString().
WindowWriteStringCC()
---------------------
Centers and writes a string around a column of the window (the CC stands
for Centered Column). If the string is longer than the width of the window,
the string is placed on column 1 of the window and is clipped at the right
edge of the window. Here is the prototype:
The attribute used to write the string is the attribute of the inside of the
window.
Page 36 The C Window Library Page 36
int WindowWriteStringCC(WPOINTER w, char *string, int row)
The first argument is the window. The second argument is the string. The
third argument is the row to write the string, and the last argument is the
column to center the string on.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringCC(w,"This",1,10);
WindowWriteStringCC(w,"is",2,10);
WindowWriteStringCC(w,"centered",3,10);
WindowWriteStringCC(w,"around",4,10);
WindowWriteStringCC(w,"column",5,10);
WindowWriteStringCC(w,"10",6,10);
}
The example above writes the text centered around column 10 of the window w.
The return values for WindowWriteStringCC() are the same as
WindowWriteString().
WindowWriteStringCCAttr()
-------------------------
The WindowWriteStringCCAttr() function works the same as the
WindowWriteStringCC() function except that an extra argument determines
the color used to write the string. Here is the prototype:
int WindowWriteStringCCAttr(WPOINTER w, char *string, int row, int col,
int attr)
The first argument is the window. The second argument is the string to write.
The third argument is the row that the string will be centered. The column
argument is the column to center the string on. The last argument is the
video attribute to use to write the string.
Page 37 The C Window Library Page 37
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringCCAttr(w,"This",1,10,REVERSE);
WindowWriteStringCCAttr(w,"is",2,10,REVERSE);
WindowWriteStringCCAttr(w,"centered",3,10,REVERSE);
WindowWriteStringCCAttr(w,"around",4,10,REVERSE);
WindowWriteStringCCAttr(w,"column",5,10,REVERSE);
WindowWriteStringCCAttr(w,"10",6,10,REVERSE);
}
The example above writes the text centered around column 10 of the window w
using the video attribute REVERSE.
The return values for WindowWriteStringCCAttr() are the same as
WindowWriteString().
WindowWriteStringRJ()
---------------------
The WindowWriteStringRJ() function writes a right justified string. Here is
the prototype:
int WindowWriteStringRJ(WPOINTER w, char *string, int row, int col)
The first argument is the window. The second argument is the string. The
third argument is the row to write the string, and the last argument is the
column to place the right edge of the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
Page 38 The C Window Library Page 38
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringRJ(w,"This",1,10);
WindowWriteStringRJ(w,"is",2,10);
WindowWriteStringRJ(w,"right",3,10);
WindowWriteStringRJ(w,"justified",4,10);
WindowWriteStringRJ(w,"on ",5,10);
WindowWriteStringRJ(w,"column",6,10);
WindowWriteStringRJ(w,"10",7,10);
}
The example above writes the text right justified on column 10 of the window
w.
The attribute used to write the string is the attribute of the inside of the
window.
The return values for WindowWriteStringRJ() are the same as
WindowWriteString().
WindowWriteStringRJAttr()
-------------------------
The WindowWriteStringRJAttr() function works the same as the
WindowWriteStringRJ() function except that an extra argument determines the
color used to write the string. Here is the prototype:
int WindowWriteStringRJAttr(WPOINTER w, char *string, int row, int col,
int attr)
The first argument is the window. The second argument is the string to write.
The third argument is the row to write the string. The col is the column to
right justify the string. The last argument is the video attribute to use to
write the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
Page 39 The C Window Library Page 39
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteStringRJAttr(w,"This",1,10,REVERSE);
WindowWriteStringRJAttr(w,"is",2,10,REVERSE);
WindowWriteStringRJAttr(w,"right",3,10,REVERSE);
WindowWriteStringRJAttr(w,"justified",4,10,REVERSE);
WindowWriteStringRJAttr(w,"on ",5,10,REVERSE);
WindowWriteStringRJAttr(w,"column",6,10,REVERSE);
WindowWriteStringRJAttr(w,"10",7,10,REVERSE);
}
The example above writes the text right justified at column 10 of the window
w using the video attribute REVERSE.
The return values for WindowWriteStringRJAttr() are the same as
WindowWriteString().
Length Controlled Write Functions
---------------------------------
The upcoming functions must have the length explicitly stated as one of the
arguments. These functions do not stop writing characters if the null
character in the string to write is reached.
WindowWriteCharacters()
-----------------------
This function writes characters from a buffer to the window. Here is the
prototype:
int WindowWriteCharacters(WPOINTER w, char *buffer, int row, int col,
int length)
The first argument is the window. The second argument is a pointer to the
buffer where the characters are stored. The third and fourth arguments are
the (row,col) position in the window to write the string, and the last
argument is the number of characters from buffer to write. The attribute
used is the attribute of the inside of the window.
Page 40 The C Window Library Page 40
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[] = "Hello World!!";
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteCharacters(w,buf,1,1,11); /* Writes "Hello World" */
WindowWriteCharacters(w,buf,2,1,13); /* Writes "Hello World!!" */
}
The return values for WindowWriteCharacters() are the same as
WindowWriteString().
WindowWriteAttributes()
-----------------------
This function writes attributes from a buffer to the window. Here is the
prototype:
int WindowWriteAttributes(WPOINTER w, char *buffer, int row, int col,
int length)
The first argument is the window. The second argument is a pointer to the
buffer where the attributes are stored. The third and fourth arguments are
the (row,col) position in the window to write the string, and the last
argument is the number of attributes from buffer to write.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char buf[13];
Page 41 The C Window Library Page 41
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<13;i++)
if (i % 2)
buf[i] = NORM;
else
buf[i] = REVERSE;
WindowWriteString(w,"Hello World!!",1,1);
GET_KEY();
WindowWriteAttributes(w,buf,1,1,13); /* Writes alternating NORM and
REVERSE attributes */
}
The return values for WindowWriteAttributes() are the same as
WindowWriteString().
WindowWriteCharAndAttr()
------------------------
The WindowWriteCharAndAttr() function writes a string of character/attribute
pairs to a window. Use this function if you have created a string of
character/attribute pairs, and want to output them easily. The string
consists of character and attributes in the following manner:
char-attr-char-attr...
Each character is followed by its corresponding video attribute.
Here is the prototype:
int WindowWriteCharAndAttr(WPOINTER w, char *buffer, int row, int col,
int length)
The first argument is the window. The second is the buffer where the
character and attributes are stored. The third and fourth is the (row,col)
position in the window to write, and the length argument is the number of
character/attribute pairs from the buffer to write. Please note the
difference in the meaning of the length argument in this function as opposed
to its use in the preceding functions.
Page 42 The C Window Library Page 42
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[26];
char *str = "Hello World!!";
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<26;i+=2,str++)
{
buf[i] = *str;
buf[i+1] = NORM;
}
WindowWriteCharAndAttr(w,buf,1,1,13);
}
The return values for WindowWriteCharAndAttr() are the same as
WindowWriteString().
WindowWriteCharactersAttr()
---------------------------
The WindowWriteCharactersAttr() function writes characters from a buffer to a
window. The difference between this function and WindowWriteCharacters() is
that a video attribute is specified. Here is the prototype:
int WindowWriteCharactersAttr(WPOINTER w, char *buffer, int row, int col,
int attr, int length)
The attr argument is the video attribute to use when writing the characters.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
Page 43 The C Window Library Page 43
WPOINTER w;
char buf[] = "Hello World!!";
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowWriteCharactersAttr(w,buf,2,1,REVERSE,13); /* Writes "Hello World!!"
using the REVERSE
attribute */
}
The return values for WindowWriteCharactersAttr() are the same as
WindowWriteString().
WindowWriteRepeatAttribute()
----------------------------
The WindowWriteRepeatAttribute() function writes an attribute a specified
number of times to a window. Here is a prototype:
int WindowWriteRepeatAttribute(WPOINTER w, int attr, int row, int col,
int count)
The attr argument is the attribute to use. The count argument specifies the
number of times to write the attribute attr to the window starting at
(row,col).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
Page 44 The C Window Library Page 44
WindowWriteString(w,"Hello World!!",1,1);
GET_KEY();
WindowWriteRepeatAttribute(w,REVERSE,1,1,13);
}
The example above illustrates that the WindowWriteRepeatAttribute() writes
the REVERSE attribute 13 times starting at row 1, column 1 of the window w.
The return values for WindowWriteRepeatAttribute() are the same as
WindowWriteString().
WindowWriteRepeatCharacter()
----------------------------
The WindowWriteRepeatCharacter() function writes a character a specified
number of times to a window. Here is a prototype:
int WindowWriteRepeatCharacter(WPOINTER w, int ch, int row, int col,
int count)
The count argument is the character to use. The count argument specifies the
number of times to write the character ch to the window starting at (row,col).
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteRepeatCharacter(w,'a',1,1,5);
WindowWriteRepeatCharacter(w,'b',2,1,5);
WindowWriteRepeatCharacter(w,'c',3,1,5);
}
The example above illustrates that the WindowWriteRepeatCharacter() writes
the letter 'a', 'b', and 'c' 5 times on rows 1, 2, and 3 respectively.
The return values for WindowWriteRepeatCharacter() are the same as
WindowWriteString().
Page 45 The C Window Library Page 45
Formatted Write Functions
-------------------------
These functions write formatted output to windows just like the printf()
function. There are two functions that do this, namely WindowPrintf()
and WindowPrintfAttr(). These functions use a format string that is similar
to the format string found in printf(). For example, %d, %s, %lf, etc. and
most of the escape sequences are supported. The list of escape sequences
supported are as follows:
\n - newline
\b - backspace
\t - tab
\a - bell
\r - carriage return
\x - hexadecimal
Where output is placed in the window
------------------------------------
The row and column of where the string will be written is determined by the
window's logical cursor. The logical cursor is advanced by both of these
functions to one column position after the last character is printed. If you
want to start at a particular row and column of the window, you must move the
cursor yourself by calling the WindowMoveCursor() function. This function is
explained later in the CURSOR POSITIONING IN WINDOWS section. If the window
is displayed, the logical cursor of the window is equivalent to the screen
cursor. If the output to the window will be obscured by other windows, the
screen cursor will also be hidden.
When the window is first opened using WindowOpen(), the logical cursor is
automatically moved to (1,1) of the window.
WindowSetWrap()
---------------
With these functions, any text that will exceed the boundaries of the window
will be wrapped to the next line. If the output will exceed the last row of
the window, the window is automatically scrolled up by one line. This is the
default action that is taken when characters exceed the right edge of the
window. If you want the output clipped instead of wrapped, you must set the
window's wrap flag using the WindowSetWrap() function.
The WindowSetWrap() function sets the window's wrap flag to either on or off.
Here is the prototype:
int WindowSetWrap(WPOINTER w, int option)
The second argument will be 0 if you want to turn the wrap flag off, or 1 if
you want to turn it on. If the wrap flag is off, the output generated by
WindowPrintf() and WindowPrintfAttr() will be terminated when the right edge
Page 46 The C Window Library Page 46
of the window is reached. If the wrap flag is on, the output is wrapped to
the next line when the right edge is reached, and the window will be scrolled
up by one line if the output will exceed the last row.
You can set the wrap flag to a window at any time.
WindowPrintf()
--------------
The WindowPrintf() function writes formatted output to the window. Here is
the prototype:
int WindowPrintf(WPOINTER w, char *format [,arg1,...])
The first argument is the window. The second argument is a format string.
The rest of the arguments are optional arguments that are written to the
window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char *s1 = "This string will wrap around to the next line\n";
char *s2 = "This escape code will ring the bell \a";
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowPrintf(w,"3+2 is equal to %d\n",3+2);
GET_KEY();
WindowPrintf(w,"i is equal to %d\nj is equal to %lf\n",i,j);
GET_KEY();
WindowPrintf(w,s1);
GET_KEY();
WindowPrintf(w,s2);
}
The above example illustrates how WindowPrintf() is used to print formatted
strings.
The return values for WindowPrintf() are the same as WindowWriteString().
Page 47 The C Window Library Page 47
WindowPrintfAttr()
------------------
The WindowPrintfAttr() function writes formatted output to the window.
The difference between WindowPrintf() and WindowPrintfAttr() is that
WindowPrintfAttr() uses a video attribute specified as an argument. Here is
the prototype:
int WindowPrintfAttr(WPOINTER w, int attr, char *format [,arg1,...])
The first argument is the window. The second argument is the video
attribute to use. The third argument is the format string. The rest of the
arguments are optional arguments that are written to the window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char *s1 = "This string will wrap around to the next line\n";
char *s2 = "This escape code will ring the bell \a";
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowPrintfAttr(w,REVERSE,"3+2 is equal to %d\n",3+2);
GET_KEY();
WindowPrintfAttr(w,REVERSE,"i is equal to %d\nj is equal to %lf\n",i,j);
GET_KEY();
WindowPrintfAttr(w,REVERSE,s1);
GET_KEY();
WindowPrintfAttr(w,REVERSE,s2);
}
The above example illustrates how WindowPrintfAttr() is used to print
formatted strings.
The return values for WindowPrintfAttr() are the same as WindowWriteString().
Page 48 The C Window Library Page 48
WRITING TITLES TO WINDOWS
-------------------------
This section only applies to bordered windows. There are two methods of
writing text to the top or bottom border of a window. Each method has its
advantages and disadvantages.
The first method is to explicitly write to the border of the window. Except
for the WindowPrintf...() functions, if you specify the row number to be 0,
the text is written on the upper border of the window. If the row number is
equal to the window height + 1, the text is written on the lower border of
the window. To access the window's height use the macro WINDOW_HEIGHT()
described later in the WINDOW MACROS section.
If you want to write a formatted string on the border of the window, use the
standard library function sprintf() to create a string of formatted output,
and then write this string with one of the WindowWrite...() functions.
Any text that is written on the borders of a window are not retained if the
window is resized using one of the WindowResize...() functions, or if the
border is changed using WindowDrawBorder(). Therefore it is a good idea to
maintain what is on the borders of the window in your own string variables.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* Specify row 0 to write on */
WindowWriteCenterString(w,"This is a title",0);
/* Now write title on bottom by using the height structure member */
WindowWriteCenterString(w,"This is a title",w->height + 1);
}
Page 49 The C Window Library Page 49
The second method is writing a string of text to either the top or bottom
border by using the WindowTitle...() functions. The advantage of using these
functions is that the strings are retained automatically if the window is
resized or the border type is changed. Another advantage is that if the
title does not fit in the boundaries of the window, the title is truncated,
but the full title is retained in a buffer. If the window is later resized
so that the title can fit, the full title will appear on the border.
The disadvantage is that only one string of text is allowed for the top and
bottom borders, and there are only three positions on each border to place
the title.
WindowTitleTop()
----------------
The WindowTitleTop() function writes a title to the top border of a window.
Here is the prototype:
int WindowTitleTop(WPOINTER w, char *title, int pos)
The first argument is the window to write the title. The second argument is
the title to write. The third argument is the position to place the title.
Here is a list of valid constants to use for the position:
TITLELEFT - Places the title starting at column 1 of the window.
TITLECENTER - Centers the title in the window.
TITLERIGHT - Right justifies the title to the last column of the window.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
WindowTitleTop(w,"This is a title",TITLELEFT);
GET_KEY();
Page 50 The C Window Library Page 50
/* center title */
WindowTitleTop(w,"This is a title",TITLECENTER);
GET_KEY();
/* right justify title */
WindowTitleTop(w,"This is a title",TITLERIGHT);
}
If there are no errors, WindowTitleTop() returns NO_ERROR.
If there are errors, WindowTitleTop() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen())
WindowTitleBottom()
-------------------
The WindowTitleBottom() function writes a title to the bottom border of a
window. Here is the prototype:
int WindowTitleBottom(WPOINTER w, char *title, int pos)
The first argument is the window to write the title. The second argument is
the title to write. The third argument is a constant that denotes the
position to place the title. A list of valid constants can be found in the
description of WindowTitleBottom() described above.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
WindowTitleBottom(w,"This is a title",TITLELEFT);
GET_KEY();
/* center title */
WindowTitleBottom(w,"This is a title",TITLECENTER);
GET_KEY();
Page 51 The C Window Library Page 51
/* right justify title */
WindowTitleBottom(w,"This is a title",TITLERIGHT);
}
If there are no errors, WindowTitleBottom() returns NO_ERROR.
If there are errors, WindowTitleBottom() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen())
WindowTitleTopAttr()
--------------------
The WindowTitleTopAttr() function writes a title to the top border of a window
with a specified color attribute. Here is the prototype:
int WindowTitleTopAttr(WPOINTER w, char *title, int pos, int attr)
The first argument is the window to write the title. The second argument is
the title to write. The third argument is a constant that denotes the
position to place the title. A list of valid constants can be found in the
description of WindowTitleTopAttr() described above. The fourth argument is
the color attribute to use.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
WindowTitleTopAttr(w,"This is a title",TITLELEFT,REVERSE);
GET_KEY();
/* center title */
WindowTitleTopAttr(w,"This is a title",TITLECENTER,REVERSE);
GET_KEY();
Page 52 The C Window Library Page 52
/* right justify title */
WindowTitleTopAttr(w,"This is a title",TITLERIGHT,REVERSE);
}
If there are no errors, WindowTitleTopAttr() returns NO_ERROR.
If there are errors, WindowTitleTopAttr() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen())
WindowTitleBottomAttr()
-----------------------
The WindowTitleBottomAttr() function writes a title to the bottom border of a
window with a specified color attribute. Here is the prototype:
int WindowTitleBottomAttr(WPOINTER w, char *title, int pos, int attr)
The first argument is the window to write the title. The second argument is
the title to write. The third argument is a constant that denotes the
position to place the title. A list of valid constants can be found in the
description of WindowTitleBottomAttr() described above. The fourth argument is
the color attribute to use.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
int i;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
/* left justify title */
WindowTitleBottomAttr(w,"This is a title",TITLELEFT,REVERSE);
GET_KEY();
/* center title */
WindowTitleBottomAttr(w,"This is a title",TITLECENTER,REVERSE);
GET_KEY();
Page 53 The C Window Library Page 53
/* right justify title */
WindowTitleBottomAttr(w,"This is a title",TITLERIGHT,REVERSE);
}
If there are no errors, WindowTitleBottomAttr() returns NO_ERROR.
If there are errors, WindowTitleBottomAttr() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen())
Page 54 The C Window Library Page 54
READING CHARACTERS AND ATTRIBUTES FROM WINDOWS
----------------------------------------------
With The C Window Library, you can read the contents of a window into a
character buffer. These functions provide the programmer with the contents of
the window at any time. The functions to perform this are
WindowReadAttributes(), WindowReadCharacters(), and WindowReadCharAndAttr().
WindowReadCharacters()
----------------------
The WindowReadCharacters() function reads the characters from a window into a
buffer. Here is the prototype.
int WindowReadCharacters(WPOINTER w, char *buffer, int row, int col,
int length)
The first argument is the window. The second argument is the buffer to store
the characters in. The third and fourth arguments are the (row,col) position
in the window to start reading from. The last argument is the number of
characters to read.
You must make sure that buffer has enough room to hold all of the characters
read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);/* Write String */
WindowReadCharacters(w,buf,1,1,13); /* Read characters */
GET_KEY();
WindowWriteString(w,buf,2,1); /* Write what we have read */
}
Page 55 The C Window Library Page 55
The example above illustrates the use of WindowReadCharacters(), which reads
the window's contents starting at (1,1) of the window. This happens to be
the string "Hello World!!". After GET_KEY() is called, the results of the
buffer are written on line 2 of the window.
If the length exceeds the right edge of the window, WindowReadCharacters()
will read up to the right edge of the window.
If there are no errors, WindowReadCharacters() returns NO_ERROR.
If there are errors, WindowReadCharacters() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for reading (use WindowOpen())
WINDOW_BOUND if the row or column specified in the window is out of bounds.
WindowReadAttributes()
----------------------
The WindowReadAttributes() function reads the attributes from a window into a
buffer. Here is the prototype.
int WindowReadAttributes(WPOINTER w, char *buffer, int row, int col,
int length)
The first argument is the window. The second argument is the buffer to store
the attributes in. The third and fourth arguments are the (row,col) position
in the window to start reading from. The last argument is the number of
attributes to read.
You must make sure that buffer has enough room to hold all of the attributes
read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
Page 56 The C Window Library Page 56
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);/* Write String */
WindowReadAttributes(w,buf,1,1,13); /* Read attributes */
GET_KEY();
WindowWriteString(w,buf,2,1); /* Write what we have read */
}
The example above illustrates the use of WindowReadAttributes(), which reads
the window's attribute contents starting at (1,1) of the window. This
happens to be the attributes of the string "Hello World!!", which is the
NORM attribute. After GET_KEY() is called, the results of the buffer are
written on line 2 of the window.
If the length exceeds the right edge of the window, WindowReadAttributes()
will read up to the right edge of the window.
If there are no errors, WindowReadAttributes() returns NO_ERROR.
If there are errors, WindowReadAttributes() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for reading (use WindowOpen())
WINDOW_BOUND if the row or column specified in the window is out of bounds.
WindowReadCharAndAttr()
----------------------
The WindowReadCharAndAttr() function reads character/attribute pairs from a
window into a buffer. Here is the prototype.
int WindowReadCharAndAttr(WPOINTER w, char *buffer, int row, int col,
int length)
The first argument is the window. The second argument is the buffer to store
the character/attribute pairs in. The third and fourth arguments are the
(row,col) position in the window to start reading from. The last argument is
the number of character/attribute pairs to read.
You must make sure that buffer has enough room to hold all of the
character/attribute pairs read in.
Page 57 The C Window Library Page 57
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buf[27] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Hello World!!",1,1);/* Write String */
WindowReadCharAndAttr(w,buf,1,1,13); /* Read character/attributes */
GET_KEY();
WindowWriteCharAndAttr(w,buf,2,1,13); /* Write what we have read */
}
The example above illustrates the use of WindowReadCharAndAttr(), which reads
the window's character/attribute contents starting at (1,1) of the window.
This happens to be the characters/attributes of the string "Hello World!!".
After GET_KEY() is called, the results of the buffer are written on line 2 of
the window.
If the length exceeds the right edge of the window,
WindowReadCharAndAttr() will read up to the right edge of the window.
If there are no errors, WindowReadCharAndAttr() returns NO_ERROR.
If there are errors, WindowReadCharAndAttr() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window was not open for reading (use WindowOpen())
WINDOW_BOUND if the row or column specified in the window is out of bounds.
Page 58 The C Window Library Page 58
HIDING WINDOWS
--------------
With The C Window Library, you can hide windows at any time without
disturbing the contents of other windows.
WindowHide()
------------
The WindowHide() function hides a window on the screen from view. The window
retains all text and shadows that may be present. Here is a prototype:
int WindowHide(WPOINTER w, int effect)
The first argument is the window, and the last argument is the special effect
to use when hiding the window. For a list of special effects, refer to the
DISPLAYING WINDOWS section.
Example :
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
#define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w1,w2,w3;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
/* Initialize all windows */
w1 = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
w2 = WindowInitialize(BORDER,2,2,20,10,REDONWHITE,NORM,DOUBLEBOX);
w3 = WindowInitialize(BORDER,3,3,20,10,BLACKONWHITE,NORM,SINGLEBOX);
/* Open all windows */
WindowOpen(w1);
WindowOpen(w2);
WindowOpen(w3);
/* Display All windows */
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
WindowDisplay(w3,3,NOEFFECT);
Page 59 The C Window Library Page 59
WindowWriteString(w1,"This is window 1",1,1);
WindowWriteString(w2,"This is window 2",2,1);
WindowWriteString(w3,"This is window 3",3,1);
GET_KEY();
WindowHide(w3,NOEFFECT);
GET_KEY();
WindowHide(w2,BRICKS);
GET_KEY();
WindowHide(w1,CONTRACT);
}
The example initializes, opens, and displays three windows. Note that you
can hide windows regardless of the order in which they were displayed. This
makes for very flexible window management.
If there is no error, WindowHide() returns NO_ERROR.
The only error that can occur is if the WPOINTER w does not exist.
WindowHide() returns BAD_WINDOW if this is the case.
Page 60 The C Window Library Page 60
CREATING COPIES OF A WINDOW
---------------------------
You can create copies of a window without going through the
WindowInitialize(), WindowOpen(), etc. cycle.
WindowCopy()
------------
The WindowCopy() function makes a copy of a previous window. The copy
will have the same colors, border type, shadow, and may have the same text as
a previous window. If the original window is a viewport on a virtual window
(virtual windows are discussed later in the VIRTUAL WINDOWS section), the
copy can also be made a viewport on the same virtual window. The only thing
that will not be copied is the (row,col) of the original window. You supply
the position of the new window. Here is the prototype:
WPOINTER WindowCopy(WPOINTER w, int row, int col, int options)
Please note that WindowCopy() returns a new WPOINTER. You must assign the
return value to a WPOINTER or you will not get easy access to the newly
created window.
The first argument is the original window to copy. This window must already
exist. The second and third arguments are the coordinates of where to place
the new window. The last argument are additional options that control
whether the window will contain the same text as the previous window, and if
the new window will be made a viewport if the original window is a viewport.
The constants used for options is as follows:
options action
------- ------
COPYTEXT Makes a copy of the text area of the original window.
MAKEVIEWPORT Turns the copy into a viewport if the original is a
viewport.
NO_OPTIONS No options desired.
As was stated before, viewports are discussed in the VIRTUAL WINDOW section
of the manual. If options is NO_OPTIONS, the windows size, border type,
shadow (if there is a shadow) and colors are copied.
Page 61 The C Window Library Page 61
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w,w2;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,45,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"This will be copied to the new window",1,1);
GET_KEY();
w2 = WindowCopy(w,3,3,COPYTEXT); /* Make a copy of w */
WindowDisplay(w2,1,NOEFFECT); /* Display this copy */
GETKEY();
WindowFreeAll(0,NOEFFECT);
}
If there is no error, WindowCopy() returns a valid WPOINTER.
If there is an error, WindowCopy() returns a WIN_NULL_PTR (a null window
pointer) and sets window_error_code to one of the following values:
NO_HEAP_MEM if there is not enough memory to allocate for the window
structure.
BAD_WINDOW_SIZE if the dimensions for the window are too large for the
physical screen.
MAX_WINDOW if there are > 254 windows defined.
Page 62 The C Window Library Page 62
SCROLLING TEXT IN WINDOWS
-------------------------
With The C Window Library, you can scroll text in a window up, or down, or
scroll just particular regions of a window. The functions used to scroll
windows are WindowScroll(), WindowScrollAttr(), WindowScrollRegion(), and
WindowScrollRegionAttr().
When specifying a direction, use the constant UP to scroll up or DOWN to
scroll down. These constants are defined in window.h.
WindowScroll()
--------------
If you want to scroll the entire window either up or down, you can use the
WindowScroll() function. Here is a prototype:
int WindowScroll(WPOINTER w, int numlines, int direction)
The first argument is the window to scroll. The second argument is the
number of lines to scroll. The last argument is the direction to scroll the
window (either UP or DOWN).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScroll(w,1,UP);
GET_KEY();
WindowScroll(w,3,DOWN);
}
The above example creates text using WindowWriteRepeatCharacter() function.
The WindowScroll() calls will scroll the window up by one line, and then
scroll the window down by 3 lines.
Page 63 The C Window Library Page 63
If there is no error, WindowScroll() returns NO_ERROR.
If there is an error, WindowScroll() will return the following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen() to
open the window for writing).
WindowScrollRegion()
--------------------
The WindowScrollRegion() functions scrolls a specified region of a window.
To use the WindowScrollRegion() function, you must describe the rectangular
region to scroll. Here is the prototype:
int WindowScrollRegion(WPOINTER w, int numlines, int urow, int ucol, int lrow,
int lcol, int direction)
Arguments 3 thru 6 describe the rectangular region. They are in the order of
upper left row, upper left column, lower right row, lower right column. All
of these coordinates are window relative. The second argument is the number
of lines to scroll. The last argument is the direction.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScrollRegion(w,1,2,2,4,10,UP);
GET_KEY();
WindowScrollRegion(w,3,7,2,9,8,DOWN);
}
Page 64 The C Window Library Page 64
The above example creates text using WindowWriteRepeatCharacter() function.
The first WindowScrollRegion() call will scroll the region described by
the rectangular coordinates (2,2) and (4,10). This region is scrolled up one
line. The second call to WindowScrollRegion() scrolls the region defined by
the rectangular region (7,2) and (9,8). This region is scrolled down by
three lines.
If there is no error, WindowScrollRegion() returns NO_ERROR.
If there is an error, the WindowScrollRegion() function will return of the
following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_BOUND if the rectangular region defined is out of bounds of the
window.
WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen() to
open the window for writing).
WindowScrollAttr()
------------------
This function works the same way as the WindowScroll() function except that
an attribute is defined for the blank lines that are created when the window
is scrolled. Here is a prototype:
int WindowScrollAttr(WPOINTER w, int numlines, int direction, int attr)
The last argument is the attribute to use for the blank lines created.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
Page 65 The C Window Library Page 65
WindowScrollAttr(w,1,UP,REDONWHITE);
GET_KEY();
WindowScrollAttr(w,3,DOWN,REDONWHITE);
}
The above example creates text using WindowWriteRepeatCharacter() function.
The WindowScrollAttr() calls will scroll the window up by one line, and then
scroll the window down by 3 lines with both scrolls using REDONWHITE as the
video attribute.
WindowScrollAttr() returns the same values as WindowScroll().
WindowScrollRegionAttr()
------------------------
This function works the same way as the WindowScrollRegion() function
except that an attribute is defined for the blank lines that are created when
the window is scrolled. Here is a prototype:
int WindowScrollRegionAttr(WPOINTER w, int numlines, int urow, int ucol,
int lrow, int lcol,int direction, int attr)
The last argument is the attribute to use for the blank lines created.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<10;i++)
WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20);
GET_KEY();
WindowScrollRegionAttr(w,1,3,5,6,15,UP,REDONWHITE);
GET_KEY();
WindowScrollRegionAttr(w,3,8,4,10,12,DOWN,REDONWHITE);
}
Page 66 The C Window Library Page 66
The above example creates text using WindowWriteRepeatCharacter() function.
The first WindowScrollRegionAttr() call will scroll the region described by
the rectangular coordinates (2,2) and (4,10). This region is scrolled one
line. The second call to WindowScrollRegionAttr() scrolls the region defined
by the rectangular region (7,2) and (9,8). This region is scrolled down by
three lines. All blank lines use the video attribute REDONWHITE.
WindowScrollRegionAttr() returns the same values as WindowScrollRegion().
Page 67 The C Window Library Page 67
CLEARING WINDOWS
----------------
The C Window Library contains functions that clears the entire window, or
clears defined rectangular regions of the window.
WindowClear()
-------------
The WindowClear() function clears an entire window to spaces. The attribute
used is the current attribute of the text area of the window. Here is the
prototype:
int WindowClear(WPOINTER w)
The only argument is the window to clear.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClear(w);
}
If there is no error, WindowClear() returns NO_ERROR.
If there is an error, WindowClear() returns the following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen() to
open the window for writing).
Page 68 The C Window Library Page 68
WindowClearAttr()
-----------------
The WindowClearAttr() function works the same way as the WindowClear()
function except that an attribute is specified. Here is the prototype:
int WindowClearAttr(WPOINTER w, int attr)
The second argument is the video attribute to use.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClearAttr(w,REDONWHITE);
}
The return values for WindowClearAttr() are the same as WindowClear().
WindowClearRegion()
-------------------
The WindowClearRegion() function clears a region of a window. To use the
WindowClearRegion() function, you must describe the rectangular region to
clear. Here is the prototype:
int WindowClearRegion(WPOINTER w, int urow, int ucol, int lrow, int lcol)
where (urow,ucol) describes the upper left of the rectangle and (lrow,lcol)
is the lower right of the window. These coordinates are window relative.
Page 69 The C Window Library Page 69
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClearRegion(w,4,4,8,15);
}
The WindowClearRegion() call will clear the region described by the
rectangular coordinates (4,4) and (8,15).
If there is no error, WindowClearRegion() returns NO_ERROR.
If there is an error, the WindowClearRegion() function will return the
following values:
BAD_WINDOW if the WPOINTER w does not exist.
WINDOW_BOUND if the rectangular region defined is out of bounds of the
window.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen() to
open the window for writing).
WindowClearRegionAttr()
-----------------------
The WindowClearRegionAttr() function works the same as the
WindowClearRegion() function, except that a video attribute is specified.
Here is the prototype:
int WindowClearRegionAttr(WPOINTER w, int urow, int ucol, int lrow, int lcol,
int attr)
The attr argument is a video attribute to use to clear the region.
Page 70 The C Window Library Page 70
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white)
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowClearRegionAttr(w,4,4,8,15,REDONWHITE);
}
The WindowClearRegionAttr() call will clear the region described by the
rectangular coordinates (4,4) and (8,15) using the video attribute defined
by the constant REDONWHITE.
The WindowClearRegionAttr() returns the same values as WindowClearRegion().
Page 71 The C Window Library Page 71
WRITING WINDOW CONTENTS TO A FILE
---------------------------------
The C Window Library allows you to print the contents of a window using the
WindowWriteTextToFile() function.
WindowWriteTextToFile()
-----------------------
The WindowWriteTextToFile() function allows you to print the contents of a
window to a file. Here is the prototype:
int WindowWriteTextToFile(WPOINTER w, char *filename, int mode)
The first argument is the window. The second argument is the file name.
This file can be any of the DOS filenames ("con", "prn", "aux", etc.).
The file specified by filename must be closed before calling
WindowWriteTextToFile(), and the file handle is automatically closed before
exiting WindowWriteTextToFile().
The last argument is the mode switch. If mode is 1, a newline ('\n') is
written to the file after each line of the window is written to the file. If
mode is 0, no newline character is written.
Example:
#include "window.h"
#include <stdio.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
FILE *outfile;
char *filename = "wintext";
char *filename2 = "wintext2";
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=1;i<=10;i++)
WindowWriteString(w,"Hello World!!",i,1);
GET_KEY();
WindowWriteTextToFile(w,filename,1); /* use newlines */
WindowWriteTextToFile(w,filename2,0); /* no newlines */
}
Page 72 The C Window Library Page 72
The example above illustrates two calls to WindowWriteTextToFile(). The
first call writes the contents of the window w to a file called "wintext".
Note that the mode parameter for the first call is 1. This will cause '\n'
to be written to the file for each line of the window. The second call
writes the window text to a file call "wintest2", with the mode parameter
being 0 (no '\n').
Please note that WindowWriteTextToFile() does not check if the file already
exists, so be careful that you do not replace files that are important to
you.
If there are no errors, WindowWriteTextToFile() returns NO_ERROR.
If there are errors, WindowWriteTextToFile() will return one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen())
FILE_CANT_OPEN if the file specified by filename cannot be open.
FILE_CANT_CLOSE if the file specified by filename cannot be closed.
Page 73 The C Window Library Page 73
SHADOWING WINDOWS
-----------------
With The C Window Library, you can place shadows on the windows created.
Shadows create a nice effect when displayed with the proper background color.
There are four positions where you can place a shadow on a window: the upper
left corner of the window, the upper right corner, the lower left corner or
the lower right corner.
The shadow consists of two components. One of these components is the part of
the shadow that is drawn either on the left or right side of the window. You
can control the width of this portion of the shadow. The other component that
makes up the shadow is the portion that is drawn either on top of or
underneath a window. You can control the height of this portion of the
shadow.
You can also control the shadows video attribute, as well as the character
that makes up the shadow itself. My suggestion is to use ASCII character 219
for the shadow character. Other ones that work well are ASCII 176, 178, and
178.
Transparent shadows are also supported.
You can place a shadow on a window at any time or take it off at any time.
The only restriction with the shadow is that the window's current position
must have room to draw the shadow.
WindowDrawShadow()
------------------
The WindowDrawShadow() function places a shadow on a window. Here is the
prototype:
int WindowDrawShadow(WPOINTER w, int shadowpos, int width, int height, int
shadowchar, int shadowattr, int transflag)
The first argument is the window that the shadow will be drawn. The second
argument is the position of the shadow. There are four possible positions:
SHADOWUPRIGHT - draws shadow on upper right corner of the window.
SHADOWUPLEFT - draws shadow on upper left corner of the window.
SHADOWLOWRIGHT - draws shadow on lower right corner of window.
SHADOWLOWLEFT - draws shadow on lower left corner of window.
The third argument is the width of the strip of the shadow that is drawn on
the right or left side of the window. The fourth argument is the height of
the strip of the shadow that is drawn on top or underneath the window. The
fifth argument is the character to use for the shadow. The sixth argument is
the attribute to use for the shadow. The last argument is a flag denoting
whether the shadow should be a transparent shadow. If the flag is 0, the
shadow is solid, otherwise the shadow is transparent.
Page 74 The C Window Library Page 74
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white) /* define normal video
attribute */
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) /* define a
blue on black
video attribute */
#define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red)
#define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
WPOINTER w0,w1; /* pointers to a window structures */
WindowInitializeSystem(); /* system initialization function */
WindowSaveInitial(0);
w0 = WindowInitialize(NOBORDER,1,1,80,25,REVERSE,REVERSE,0);
WindowOpen(w0);
WindowDisplay(w0,1,NOEFFECT);
w1 = WindowInitialize(BORDER,5,5,40,15,BLUEONBLACK,REDONBLACK,SINGLEBOX);
WindowOpen(w1);
WindowDrawShadow(w1,SHADOWUPLEFT,2,1,219,REVERSE,0);
WindowDisplay(w1,1,NOEFFECT);
WindowWriteString(w1,"Press a key to move shadow",1,1);
GET_KEY();
WindowDrawShadow(w1,SHADOWUPRIGHT,2,1,219,REVERSE,0);
WindowWriteString(w1,"Press a key again",2,1);
GET_KEY();
WindowDrawShadow(w1,SHADOWLOWLEFT,2,1,219,REVERSE,0);
WindowWriteString(w1,"Press a key once more",3,1);
GET_KEY();
WindowDrawShadow(w1,SHADOWLOWRIGHT,2,1,219,REVERSE,0);
GET_KEY();
WindowClose(w1,NOEFFECT);
WindowClose(w0,NOEFFECT);
}
The above example illustrates the use of WindowDrawShadow().
If there is no error, WindowDrawShadow() returns NO_ERROR.
If there are errors, WindowDrawShadow() returns one of the following:
BAD_WINDOW if the window does not exist.
WINDOW_BOUND if a shadow could not be drawn because of window location and
the height and/or width of the shadow will exceed the screen edges.
Page 75 The C Window Library Page 75
WindowRemoveShadow()
--------------------
The WindowRemoveShadow() function removes a shadow from a window, and takes
a single argument, namely the window pointer. Here is the prototype:
int WindowRemoveShadow(WPOINTER w)
If there are no errors or the window does not have a shadow,
WindowRemoveShadow() returns NO_ERROR.
If there are errors, WindowRemoveShadow() returns the following value:
BAD_WINDOW if the window does not exist.
Page 76 The C Window Library Page 76
SEE-THRU WINDOWS
----------------
You can create windows that have borders, but do not overwrite the screen
underneath. These windows are called see-thru windows.
When creating see-thru windows the WindowMakeSeeThru() function is used to
make a defined window a see-thru window.
You can turn a non-seethru window into a seethru window and vice-versa by
calling the WindowMakeNormal() function.
WindowMakeSeeThru()
-------------------
The WindowMakeSeeThru() function turns a normal window into a see-thru
window. Here is a prototype:
int WindowMakeSeeThru(WPOINTER w)
The only argument is the window pointer. You can make a window a see-thru
window at any time, including if it is hidden. If there is text in the
normal window before making it a see-thru window, the text is retained. If
text is written to a see-thru window, the text is written to the window's
internal write buffer, but is not displayed on the screen.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,5,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowMakeSeeThru(w);
GET_KEY();
WindowFree(w,NOEFFECT);
}
Page 77 The C Window Library Page 77
The example above displays a normal window, and then turns the normal window
into a see-thru window when a key is pressed.
If there are no errors, WindowMakeSeeThru() returns NO_ERROR.
If there are errors, WindowMakeSeeThru() returns the following value:
BAD_WINDOW if the window does not exist.
WindowMakeNormal()
------------------
The WindowMakeNormal() function turns a see-thru window into a normal text
window. Any text that may have been written to the window will be displayed.
Here is the prototype:
int WindowMakeNormal(WPOINTER w)
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,5,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowMakeSeeThru(w);
GET_KEY();
WindowMakeNormal(w);
}
The example above demonstrates the WindowMakeNormal() function.
If there are no errors, WindowMakeNormal() returns NO_ERROR.
If there are errors, WindowMakeNormal() returns the following value:
BAD_WINDOW if the window does not exist.
Page 78 The C Window Library Page 78
MOVING AND SLIDING WINDOWS
--------------------------
With The C Window Library, you can move and slide windows on the screen. The
functions that perform this are the WindowMove() and WindowSlide().
WindowMove()
------------
The WindowMove() function moves a window to a new location on the screen.
Here is the prototype:
int WindowMove(WPOINTER w, int row, int col)
The first argument is the window. The second and third arguments are the
row and column on the physical screen to place the upper left hand corner of
the window. Note that row and column are screen relative coordinates, not
window relative. This is one of the few functions where row and column
denote a screen relative coordinate and not a window relative coordinate.
If the row and/or column is out of bounds, the window is moved as far as
possible.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white) /* define video
attribute */
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) /* define
video attribute */
main()
{
WPOINTER w; /* pointer to a window structure */
WindowInitializeSystem(); /* system initialization function */
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM,SINGLEBOX);
WindowOpen(w); /* display window on the screen */
WindowWriteString(w,"Press a key to move me",1,1);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowMove(w,12,14); /* move the window to row 12, column 14 of the
screen */
}
The example above moves the window from its original position (1,1) to
(12,14).
If there is no error WindowMove() returns NO_ERROR.
If there are errors WindowMove() returns the following value:
BAD_WINDOW if the window does not exist.
Page 79 The C Window Library Page 79
WindowSlide()
-------------
The WindowSlide() function "slides" a window from one position on the screen
to another. Here is the prototype:
int WindowSlide(WPOINTER w, int direction, int units)
The first argument is the window. The second argument tells in which
direction to move the window, either up, down, left, or right. The
constants to use for up, down, left, and right are UP, DOWN, LEFT, and
RIGHT, respectively. The third argument tells how many rows or columns to
move the window. If the number of units will cause the window to exceed the
boundaries of the screen, the window is moved as far as possible.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white) /* define video
attribute */
#define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) /* define
video attribute */
main()
{
WPOINTER w; /* pointer to a window structure */
WindowInitializeSystem(); /* system initialization function */
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,BLUEONBLACK,NORM,SINGLEBOX);
WindowOpen(w); /* display window on the screen */
WindowWriteString(w,"Press a key to slide right",1,1);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowSlide(w,RIGHT,20);
WindowWriteString(w,"Press a key to slide down",2,1);
GET_KEY();
WindowSlide(w,DOWN,10);
WindowWriteString(w,"Press a key to slide left",3,1);
GET_KEY();
WindowSlide(w,LEFT,20);
WindowWriteString(w,"Press a key to slide up",4,1);
GET_KEY();
WindowSlide(w,UP,20);
}
The example above illustrates how to use the WindowSlide() function.
The return values for WindowSlide() are the same as WindowMove().
Page 80 The C Window Library Page 80
CURSOR POSITIONING IN WINDOWS
-----------------------------
You can change the position of the cursor and its shape in the windows you
create with The C Window Library.
Cursor Maintenance in The C Window Library
------------------------------------------
As was stated before, The C Window Library can write to any window at any
time. This makes the question "which window owns the cursor?" a hard
question to answer. One method is that the window being updated either by
writing text, clearing, etc. should have immediate control of the cursor.
The approach The C Window Library has taken is that the top-most window
always has control of the cursor. The topmost window is determined by its
rank number. Windows with low rank numbers overlay windows with higher rank
numbers.
Creating Cursor Shapes
----------------------
The C Window Library has three pre-defined cursor shapes; INVISIBLE, THIN,
and BLOCK. An INVISIBLE cursor hides the cursor, a BLOCK shape creates a
"fat" cursor, and THIN creates a thin cursor. If you want to define your own
cursor shapes, use the CREATE_CURSOR_SHAPE() macro. This macro takes two
arguments the first argument is the beginning scan line, and the second
argument is the ending scan line. Scan lines determine the height of the
cursor. For monochrome systems, the scan lines range from 0 to 13. In a
color system, the scan lines range from 0 to 7. A THIN cursor has its
starting scan line at 6 and its ending scan line at 7 for color systems, and
for monochrome systems, the starting scan line is 11 and its ending scan line
is at 12. If the starting scan line number is greater than the ending scan
line number, the cursor takes on a 'double' cursor shape. Experiment with
different starting and ending scan lines for the desired effect.
WindowChangeCursor()
--------------------
The WindowChangeCursor() function changes the shape of the cursor in a
window. Here is the prototype:
int WindowChangeCursor(WPOINTER w, int shape)
The first argument is the window. The second argument is the desired cursor
shape.
Page 81 The C Window Library Page 81
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to change cursor",1,1);/* Write String */
GET_KEY();
WindowChangeCursor(w,BLOCK);
WindowWriteString(w,"Press a key to change cursor again",2,1);
GET_KEY();
WindowChangeCursor(w,INVISIBLE);
WindowWriteString(w,"Press a key to change cursor again",3,1);
GET_KEY();
WindowChangeCursor(w,THIN);
}
If there are no errors, WindowChangeCursor() returns NO_ERROR.
If there are errors, WindowChangeCursor() returns the following value:
BAD_WINDOW if the window does not exist.
WindowMoveCursor()
------------------
The WindowMoveCursor() functions moves the cursor in a window to a new
location in the window. Here is the prototype:
int WindowMoveCursor(WPOINTER w, int row, int col)
The first argument is the window, and the second and third arguments are the
new (row,col) position in the window to place the cursor.
Page 82 The C Window Library Page 82
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to move cursor",1,1);/* Write String */
GET_KEY();
WindowMoveCursor(w,7,5); /* Move Cursor To row 7, column 5 of the window */
}
If there are no errors, WindowMoveCursor() returns NO_ERROR.
If there are errors, WindowMoveCursor() returns the following values:
BAD_WINDOW if the window does not exist.
WINDOW_BOUND if either new row or column number is out of the boundaries of
the window.
WindowGetCursorShape()
----------------------
The WindowGetCursorShape() function returns the starting and ending scan lines
of the cursor defined in a window. Here is the prototype:
int WindowGetCursorShape(WPOINTER w, int *startline, int *endline)
The startline and endline arguments are pointers to integers that will
contain the starting and ending scan lines of the cursor when
WindowGetCursorShape() returns.
Page 83 The C Window Library Page 83
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int startline,endline;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowGetCursorShape(w,&startline,&endline);
WindowPrintf(w,"The starting scan line is %d\nThe ending scan line is %d",
startline,endline);
}
The example above calls WindowGetCursorShape() and uses WindowPrintf() to
print what the starting and ending scan lines are.
If there are no errors, WindowGetCursorShape() returns NO_ERROR.
If there are errors, WindowGetCursorShape() returns the following values:
BAD_WINDOW if the window does not exist.
WindowGetCursorPosition()
-------------------------
The WindowGetCursorPosition() function gives the current row and column of
the cursor in a window. Here is the prototype:
int WindowGetCursorPosition(WPOINTER w, int *row, int *col)
The row and col arguments are pointers to integers that will contain the row
and column of the cursor after WindowGetCursorPosition() is called.
Page 84 The C Window Library Page 84
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
int row,col;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowMoveCursor(w,7,4);
WindowGetCursorPosition(w,&row,&col);
WindowPrintf(w,
"The row of the cursor is %d\nThe column of the cursor is %d",
row,col);
}
If there are no errors, WindowGetCursorPosition() returns NO_ERROR.
If there are errors, WindowGetCursorPosition() returns the following value:
BAD_WINDOW if the window does not exist.
Page 85 The C Window Library Page 85
GETTING INPUT FROM WINDOWS
--------------------------
With The C Window Library, you can read input from windows. The input can be
simple string input, or inputting strings with a character mask. There is
also support for scrolling input fields.
Input Manager
-------------
The input manager are functions internal in The C Window Library that control
editing, checking for invalid characters, cursor movement, etc.
Regular Expressions
-------------------
With The C Window Library, you specify exactly what characters are to be
expected for every input position by using a special string of characters
called a regular expression (a pattern matching string).
Note:
For those who are familiar with regular expressions, there is a difference
between the regular expressions you will see here, and the regular
expressions you will find in certain text editors, or in computer language
syntax definitions. One major difference is that there are no wild cards
denoting an arbitrary number of repeated characters (which is usually denoted
by a '*' or a '+'), and there are no 'match begin of string' and 'match end
of string' functions.
An example of a regular expression would be the string "[A-Z]" which means
only those characters that are between A and Z, inclusive, are to be
accepted as valid input characters. Of course, the ASCII collating sequence
is used.
The following characters have special meanings in regular expressions:
Character Purpose
--------- -------
Forward Slash (/) Removes the special meaning of the next
character in the regular expression.
Brackets ([]) Encloses a set of characters to be matched
with the current character entered at the
keyboard. There are other special symbols
that can appear in brackets:
---------------------------------------------
Page 86 The C Window Library Page 86
Carat (^) This symbol states that the
character entered at the keyboard
must not match any character in
the brackets. The carat must be
the first character after the
left bracket ([), otherwise the
carat is taken literally as just
another character.
Dash (-) Matches character entered at
keyboard with characters in ASCII
order between (inclusive) the
characters on either side of the
dash.
Dot (.) Matches any displayable ASCII
character.
There are two categories of regular expressions; namely simple and complex.
Simple regular expressions only specify a single character to be entered from
the keyboard, while complex regular expressions specify that more than a
single character must be entered from the keyboard.
Here are examples of simple regular expressions:
Simple
Regular Expression What will be accepted
------------------ ---------------------
[0-9] Accept any single digit character.
[3-7] Accept single digit character between '3' and
'7' inclusive.
[A-Z] Accept a letter between 'A' and 'Z' inclusive.
[A-Za-z] Accept a letter between 'A' and 'Z' or a
letter between 'a' and 'z'.
[ABCD] Accept either 'A', 'B', 'C', or 'D'.
[A-Za-z0-9] Accept anything between 'A' and 'Z', or
'a' and 'z', or '0' and '9'
[0-9ABCD] Accept '0' thru '9', 'A', 'B', 'C', or 'D'.
[^A] Accept any character except 'A'.
[^A-Z] Accept any character except the characters
between 'A' and 'Z' (inclusive).
Page 87 The C Window Library Page 87
[A-/[] Accept any character between 'A' and '[',
inclusive. Please note the use of the forward
slash to denote that the left bracket has no
special meaning.
[A Z] Accept 'A', the space character, or 'Z'.
[A/-Z] Accept 'A', the minus (-), or 'Z'.
[/-///]] Accept the minus (-), the forward slash (/),
or the right bracket (]).
[!-&] Accept the ASCII characters between '!' and
'&', inclusive.
A Accept the letter 'A'. Note that this is
equivalent to [A].
[9] Accept the digit '9'.
. Accept any character.
[] Accept no key and call user defined function
(explained later in the UNDEFINED KEYSTROKE
PROCESSING section).
Remember, all of the above expressions process only one character entered at
the keyboard, even though some of the expressions can accept a variety of
characters.
As you can see there are many possibilities you can make up. However the
above forms of a regular expressions only work for one character entered at
the keyboard. What if you want to enter a persons name, address, social
security number etc.? You can concatenate (glue together) the regular
expressions above to form a chain of regular expressions. This resulting
chain is called a complex regular expression. Here are a few examples of
complex regular expressions:
Regular Expression What will be accepted
------------------ ---------------------
[A-Z][0-9] The first character entered must be between
'A' and 'Z'. The second character entered
must be between '0' and '9'.
[A-Z][^A-Z][0-9] Enter three characters. The first must be
between 'A' and 'Z'. The second can be any
character except anything between 'A' and 'Z',
and the third character must be between '0'
and '9'.
[1-9][0-9][0-9][0-9][0-9] Enter five characters. The first must
be between '1' and '9'. The other four
characters must be between '0' and '9'.
Page 88 The C Window Library Page 88
[A-Z][][0-9] The first character must be between 'A' and
'Z', the second input position calls a user
defined function (explained in UNDEFINED
KEYSTROKE PROCESSING), and the third
character must be between '0' and '9'.
As you can see again, the strings can get pretty long if you wanted to setup a
thirty character input specification, for instance, a persons name. To save
time typing, you can use a multiplying factor in the regular expression. A
multiplying factor is a number that is placed before a simple regular
expression to denote that the simple regular expression is repeated.
Here are a few examples:
Regular Expression What will be accepted
------------------ ---------------------
25[A-Z] Enter twenty-five characters. All the
characters must be between 'A' and 'Z'.
10[0-9] Enter ten characters. All must be between
'0' and '9'.
5[A-C] 3[1-3] Enter nine characters. The first five must be
between 'A' and 'C' the sixth must be the
space character, and the last three must be
between '1' and '3'. Please note the space
embedded in the string just before the
multiplying factor 3.
[1-9]2X/[5[^A-Z]/1 Enter nine characters. The first must be
between '1' and '9'. The second and third
must be 'X'. The fourth is the left bracket
([). The next five characters entered can be
any character except anything between 'A' and
'Z', and the last character to accept is a
'1'. Please note the use of the forward slash
just before the second left bracket and just
before the last character ('1'). The
forward slash before the '1' makes sure the
'1' is not to be confused with a multiplying
factor of 1.
[A-Z]/.. Enter three characters. The first must be
between 'A' and 'Z'. The second is the '.',
and the third is any character.
10[A-Z]3[] Enter thirteen characters. The first ten
must be between 'A' and 'Z', and the last
three input positions will call a user
defined undefined key function (explained
later in the UNDEFINED KEYSTROKE PROCESSING
section).
Page 89 The C Window Library Page 89
The only limitation to what you can do with regular expressions is that you
cannot nest regular expressions. For example:
[A-[A-Z]] or 20[20[a-z]]
It is ok to say [9-0] instead of [0-9]. They are both equivalent and both
accepted by The C Window Library, so there is no need to know your ASCII
table by heart, although it is advantageous to learn it if you want to create
sophisticated regular expression strings. You can even use the IBM extended
character set (ASCII values above 127) in the regular expression string.
Editing Input
-------------
The C library function gets(x), gets a string from the keyboard and points
the character pointer x to the string. This function has limited editing
capabilities. The only keys recognized are the backspace, which serves as a
destructive backspace (erases character immediately to the left) and the
enter key when the user has typed in the desired string. With The C Window
Library, you have much more editing capabilities.
The editing functions have the following default key values:
Mapped
Function Key Position
-------- --- ------
Move cursor left Left Arrow 0
Move cursor right Right Arrow 1
Delete character at cursor Del (on keypad) 2
Toggle Insert/Overwrite mode Insert (on keypad) 3
Erase Input and go to first column ^E 4
Destructive backspace Backspace 5
Accept Input and return Enter 6
Accept default and return Escape 7
Go to first column Home 8
Move cursor to last char. entered End 9
Here is a list of what the key functions perform:
Move cursor left - Moves the cursor left one character. If the beginning of
the input field is encountered the cursor is not moved.
Move cursor right - Moves the cursor right one character. If the end of the
input field is encountered, the cursor is not moved.
Delete character at cursor - Deletes the character at the position of the
cursor. If in insert mode, any input to the
right of the cursor is moved one character to
the left. If in overwrite mode, no characters
are moved.
Page 90 The C Window Library Page 90
Toggle Insert/Overwrite Mode - toggles the input between insert and overwrite
mode. If in insert mode, the default cursor
is an underline cursor. If in overwrite mode,
the default cursor is a full block.
Erase Input - Deletes all characters inputted and moves the cursor to the
first input position.
Destructive Backspace - deletes the character immediately to the left of the
cursor and moves the cursor to the left one
character. If insert mode is on, the characters from
the current cursor position to the end of the input
field are also moved.
Accept string - Accepts the string that is inputted and returns the string.
Accept default and return - Returns the default string given to the input
routine.
Go to first column - Moves cursor to the first input position.
Go to last character - Moves cursor to the last character in the current input
string.
The keys used to perform these functions can be changed. The mapped position
is the offset in a table of key functions. By changing the value there, you
can change the key used to perform these functions. If you do want to change
these keys, I recommend using the key definitions found in the keycodes.h
file. For example, if you wanted Control-B to be the destructive backspace
you would do as follows:
window_edit_key[5] = CTRLB;
The table of key functions is stored in the array window_edit_key. The CTRLB
stands for Control-B and its definition is found in the keycodes.h file. To
totally undefine a key definition, assign a 0 to the desired array position
in window_edit_key. For example:
window_edit_key[2] = 0;
undefines the delete character at cursor definition.
When changing keys, make sure that the definitions all have unique key
combinations. If you desire more keystrokes for a particular key function,
see Undefined Keystroke Processing below.
Last Key Value
--------------
On exit of any of the input functions, the global integer last_key_hit
contains the ascii code (scan code) of the key that was used to exit the
input function.
Page 91 The C Window Library Page 91
Default Cursor Types and Editing Mode
-------------------------------------
By default, The C Window Library starts editing input in overstrike mode.
This means that characters are overwritten when the cursor is placed on a
character. The opposite of overstrike mode is insert mode, which pushes the
characters to the right of the cursor over by one input position when a
character is entered. Also, the default cursor type for overstrike mode is a
block cursor, and the default cursor for insert mode is a thin cursor. You
can change the startup mode, as well as the cursor types.
The global variables default_cursor_type and default_cursor_mode store the
values of the cursor shapes and the startup mode.
The default_cursor_type is an array of two integers. The OVERSTRIKEMODE
constant is the position in the default_cursor_type array of where the
overstrike shape of the cursor is stored. The INSERTMODE constant is
the position in default_cursor_type of where the insert shape of the
cursor is stored. Here is an example of how you would change the
cursor types.
#include "window.h"
main()
{
WindowInitializeSystem();
/*...*/ /* Some code */
default_cursor_type[OVERSTRIKEMODE] = CREATE_CURSOR_SHAPE(6,7);
default_cursor_type[INSERTMODE] = THIN;
}
The CREATE_CURSOR_SHAPE() macro creates a cursor shape by using the first
argument as the starting scan line of the cursor, and the second argument as
the ending scan line. Refer to VIDEO MACROS section for more information on
CREATE_CURSOR_SHAPE(). The THIN constant is a predefined constant that
stands for a thin cursor. The other predefined constants for cursor shapes
are BLOCK and INVISIBLE.
To change the startup mode when an input function is called, you must change
the default_cursor_mode global variable. Here is how you would change the
default mode:
#include "window.h"
main()
{
WindowInitializeSystem();
/*...*/ /* Some code */
default_cursor_mode = OVERSTRIKEMODE;
}
Use the constants OVERSTRIKEMODE and INSERTMODE for the desired mode.
Page 92 The C Window Library Page 92
Editing using a character mask
------------------------------
The C Window Library also provides input functions that use character masks.
For example to enter a date, you might want the user to enter a date in
MM-DD-YY format. Instead of the user having to enter the hyphens, it would be
advantageous if the input field already had hyphens, and the cursor will
advance or back up to the next input position, jumping over any hyphens
encountered. You can accomplish this by using a character mask.
The mask is a character string which is made up of displayable characters, and
a special character used to denote an input position. For example, a date
mask would look like this:
__-__-__
The hyphens are displayed in the window, but the underscores are not
displayed. The underscores are used as a place holder, i.e. a place where
input is expected. By default, the input position character is an underscore,
but you can change this. Another example would be a social security mask:
___-__-____
a telephone mask:
(___) ___-____ ext: ____
another date mask:
__/__/__
If a character is deleted or inserted, the input manager is smart enough to
move characters so that they do not clobber the characters that are not part
of the input field.
Editing Functions
-----------------
The following are functions that can be used to edit input with The C Window
Library.
WindowGetString()
-----------------
The WindowGetString() function gets a string from a window starting at a
certain row and column of the window. Here is the prototype:
int WindowGetString(WPOINTER w, int row, int col, char *buffer,
int fillchar, int minchars, int maxwidth, int options,
int startpos, char *regexp)
Page 93 The C Window Library Page 93
The first argument is the window pointer. The second and third arguments are
the row and column of where the input begins. The fourth argument is a
pointer to a character buffer where the input characters will be stored.
Whatever null terminated string is stored in the character buffer prior to
calling WindowGetString() will be used as a default string. For example:
strcpy(str,"ABC");
WindowGetString(w,2,1,str,' ',3,3,0,"3[A-Z]");
The default value of "ABC" will be displayed in the window when
WindowGetString() is called. Therefore, make sure that your string buffer
has a 0 in the 0th position if you want to make sure your input is empty when
WindowGetString() is called. When inputting information, hitting the Escape
key (or whatever the current key definition is for window_edit_key[7]) will
abort input and will return the original default string.
The fifth argument is the fill character. This character is used to fill any
unfilled input positions on the window. Instead of having spaces for unfilled
positions, you can have any character. Try ASCII 177 or the underline
character. You may like the effect.
The sixth argument is the minimum number of characters to accept. If the
number of characters entered is less than minchars, the input manager will
not accept the input. However, you can change this by allowing the input
manager to call a user defined routine when it detects that the minimum
number of characters was not satisfied. More information on this later in
this section.
The seventh argument is the maximum width of the displayable input field.
This argument allows for scrollable input fields. If the maximum width of
the displayable field is less than the total number of characters in the
input field, the field will scroll right and left depending on the input
position. If the input cursor exceeds the right edge of the displayable
field, the input is scrolled right until the next input position is visible.
If the cursor is moved beyond the left edge of the displayable field, the
input is scrolled left until the previous input position comes into view.
Scrolling input fields allow for large input fields in small windows.
The eighth argument is an integer representing the various options available
for the input field. The various options available will be discussed later
on.
The ninth argument is the starting position in the input string of where the
cursor will be placed. Position numbers start from 1 to the maximum number
of input positions. For most applications, the starting position is usually
1. If the starting position is not within bounds of the input string, the
starting position is assumed to be 1.
The last argument is the regular expression to use for the input. Make
sure that the input buffer you provide is large enough to hold the maximum
number of characters plus one more character for the terminating null
character.
Page 94 The C Window Library Page 94
More Examples:
WindowGetString(w,2,1,str,' ',1,1,NO_OPTIONS,1,"[YyNn]");
This will accept one character but only if the character is 'Y','y','N', or
'n'. Another example is this:
WindowGetString(w,2,1,str,' ',5,5,NO_OPTIONS,1,"5[0-9]");
This will allow the user to enter five digit characters.
To accept all characters, use this:
WindowGetString(w,2,1,str,' ',3,3,NO_OPTIONS,1,".");
Example Program:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is NULL */
WindowWriteString(w,"Enter Your first name :",1,1);
WindowGetString(w,2,1,buffer,' ',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
WindowWriteString(w,"Now Enter your last name:",6,1);
/* Note that the last string is now used as a default */
WindowGetString(w,7,1,buffer,' ',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
Page 95 The C Window Library Page 95
If there are no errors, WindowGetString() returns NO_ERROR.
If there are errors, WindowGetString() returns the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen())
NO_HEAP_MEM if there is not enough memory to allocate for internal buffers.
NO_INPUT_CHARS if the regular expression indicates no characters to accept.
WindowGetStringAttr()
---------------------
The WindowGetStringAttr() function is the same as the WindowGetString()
function described above except that a video attribute is used for the input
entered. Here is the prototype:
int WindowGetStringAttr(WPOINTER w, int row, int col, char *buffer,
int fillchar, int minchars, int maxwidth,
int options, int startpos, int attr, char *regexp)
Note that attr is the tenth argument. This is the video attribute to use when
receiving input.
Example Program:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is NULL */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter Your first name :",1,1);
WindowGetStringAttr(w,2,1,buffer,' ',0,40,NO_OPTIONS,1,REVERSE,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
WindowWriteString(w,"Now Enter your last name:",6,1);
Page 96 The C Window Library Page 96
/* Note that the last string is now used as a default */
WindowGetStringAttr(w,7,1,buffer,' ',0,40,NO_OPTIONS,1,REVERSE,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
The return values for WindowGetStringAttr() are the same as
WindowGetString().
WindowGetMaskString()
---------------------
The WindowGetMaskString() function is the same as the WindowGetString()
except that a character mask is used when editing the input. Here is the
prototype:
int WindowGetMaskString(WPOINTER w, int row, int col, char *buffer,
char *mask, int fillchar, int minchars,
int maxwidth, int options, int startpos,
char *regexp)
The mask argument is an extra argument. This is the character mask to use
when editing the input. The string returned in the buffer does not contain
any characters that are used for the mask. For instance, if the mask is
"__/__/__", and the string entered is "121589", WindowGetMaskString() will
place "121589" into the buffer. If you want to create a string with the
components separated according to a mask pattern, use the
TranslateStringToMaskString() function described later in the manual.
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define TELMASK "(___)___-____ ext:____"
#define SSMASK "___-__-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter Your Telephone No.",1,1);
Page 97 The C Window Library Page 97
WindowGetMaskString(w,2,1,buffer,TELMASK,' ',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following phone no:",3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
memset(buffer,0,sizeof(buffer));
WindowWriteString(w,"Now Enter your Soc. Sec. Number:",6,1);
WindowGetMaskString(w,7,1,buffer,SSMASK,' ',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
If there are no errors, WindowGetMaskString() returns NO_ERROR.
If there are errors, WindowGetMaskString() returns the following:
BAD_WINDOW if the window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen())
NO_HEAP_MEM if there is not enough memory to allocate for internal buffers.
WindowGetMaskStringAttr()
-------------------------
The WindowGetMaskStringAttr() functions works the same way as
WindowGetMaskString() except that WindowGetMaskStringAttr() allows you to
specify a video attribute to use for the characters that are entered. Here
is the prototype:
int WindowGetMaskStringAttr(WPOINTER w, int row, int col, char *buffer,
char *mask, int fillchar, int minchars,
int maxwidth, int options, int startpos,
int attr, char *regexp)
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
#define TELMASK "(___)___-____ ext:____"
#define SSMASK "___-__-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
Page 98 The C Window Library Page 98
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter Your Telephone No.",1,1);
WindowGetMaskStringAttr(w,2,1,buffer,TELMASK,' ',0,40,NO_OPTIONS,1,
REVERSE,"40.");
WindowWriteString(w,"You entered the following phone no:",3,1);
WindowWriteString(w,buffer,4,1);
GET_KEY();
memset(buffer,0,sizeof(buffer));
WindowWriteString(w,"Now Enter your Soc. Sec. Number:",6,1);
WindowGetMaskStringAttr(w,7,1,buffer,SSMASK,' ',0,40,NO_OPTIONS,1,
REVERSE,"40.");
WindowWriteString(w,"You entered the following:",8,1);
WindowWriteString(w,buffer,9,1);
}
The return values for WindowGetMaskStringAttr() are the same as
WindowGetMaskString().
Getting Passwords
-----------------
The C Window Library also allows you to receive hidden input. The functions
to perform this are WindowGetPassword(), WindowGetMaskPassword(),
WindowGetPasswordAttr() and WindowGetMaskPasswordAttr(). These functions are
similar to the other WindowGetxx() functions. except that a character
specified by you is displayed instead of the actual key pressed.
WindowGetPassword()
-------------------
The WindowGetPassword() function gets hidden input from a window. Here is
the prototype:
int WindowGetPassword(WPOINTER w, int row, int col, char *buffer,
int fillchar, int passchar, int minchars, int maxwidth,
int options, int startpos, char *regexp)
The first argument is the window pointer. The second and third arguments are
the (row,col) to start receiving input. The fourth argument is the buffer
to store the inputted characters. The fifth argument is the character to use
to fill empty input positions on the screen. The sixth argument is the
character to display to the screen when a key is pressed. The last four
arguments are the same as the WindowGetString()'s last four arguments.
For example, if the user typed "ABCDEF", and the passchar is '*', the screen
will display "******". Notice the asterisk is displayed instead of the
actual characters inputted.
Page 99 The C Window Library Page 99
Example Program:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Password",1,1);
WindowGetPassword(w,2,1,buffer,' ','*',0,40,NO_OPTIONS,1,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetPassword() are the same as
WindowGetMaskString().
WindowGetPasswordAttr()
-----------------------
The WindowGetPasswordAttr() function is the same as WindowGetPassword() except
that a video attribute is specified for the input characters. Here is the
prototype:
int WindowGetPasswordAttr(WPOINTER w, int row, int col, char *buffer,
int fillchar, int passchar, int minchars,
int maxwidth, int options, int startpos,
int attr, char *regexp)
Please note that the attribute argument is the next to last argument in the
function.
Example Program:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
char buffer[80];
Page 100 The C Window Library Page 100
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Password",1,1);
WindowGetPasswordAttr(w,2,1,buffer,' ','*',0,40,NO_OPTIONS,1,REVERSE,
"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetPasswordAttr() are the same as
WindowGetMaskString().
WindowGetMaskPassword()
-----------------------
The WindowGetMaskPassword() function works just like WindowGetPassword()
except that a character mask is supplied. Here is the prototype:
int WindowGetMaskPassword(WPOINTER w, int row, int col, char *buffer,
char *mask, int fillchar, int passchar,
int minchars, int maxwidth, int options,
int startpos, char *regexp)
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define CREDITCARDMASK "____-____-____-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
Page 101 The C Window Library Page 101
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Credit Card #",1,1);
WindowGetMaskPassword(w,2,1,buffer,CREDITCARDMASK,' ','*',0,40,NO_OPTIONS,
1,"40.");
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetMaskPassword() are the same as
WindowGetMaskString().
WindowGetMaskPasswordAttr()
---------------------------
The WindowGetMaskPasswordAttr() function works just like
WindowGetMaskPassword() except that a video attribute is supplied. Here is
the prototype:
int WindowGetMaskPasswordAttr(WPOINTER w, int row, int col, char *buffer,
char *mask, int fillchar, int passchar,
int minchars, int maxwidth, int options,
int startpos, int attr, char *regexp)
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
#define CREDITCARDMASK "____-____-____-____"
WPOINTER w;
char buffer[80];
main()
{
int i,row,col;
buffer[0] = 0; /* Make sure first character is null */
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
buffer[0] = 0; /* Make sure first character is null */
WindowWriteString(w,"Enter A Credit Card #",1,1);
WindowGetMaskPasswordAttr(w,2,1,buffer,CREDITCARDMASK,' ','*',0,40,
NO_OPTIONS,1,REVERSE, "40.");
Page 102 The C Window Library Page 102
WindowWriteString(w,"You entered the following:",3,1);
WindowWriteString(w,buffer,4,1);
}
The return values for WindowGetMaskPasswordAttr() are the same as
WindowGetMaskString().
Page 103 The C Window Library Page 103
UNDEFINED KEYSTROKE PROCESSING
------------------------------
Another powerful feature of the input functions is that you can call a
function for keys that are not in the current key definitions. For instance,
say you want the Enter key AND Control-R to mean accept the input. Since
there is only room for one definition for accept input, you can write a
function that checks for the Control-R key, and return a number to the input
manager as to what action to take.
The undef_fkey_func and undef_akey_func function pointers
---------------------------------------------------------
There are two global variables, undef_fkey_func and undef_akey_func. Both of
these function pointers are defined in the file key.h. These two variables
are pointers to functions that return an integer. By setting these functions
to point to your own functions, you can process undefined keystrokes yourself
and return to the input manager what action to take.
The undef_fkey_func is used to define keys that are not normal ASCII keys.
For instance, Control key and Alt key combinations, the F-keys, PgDn and PgUp,
etc. The undef_akey_func is used to define normal ASCII keys (keys with ASCII
values between 32 and 255, inclusive).
Whenever an undefined key is encountered, the input manager will pass the
string that has been currently entered, the current key pressed, the current
position number of the character being processed, and a pointer to a new
position to place the input cursor. The prototype for this function is as
follows:
int (*undef_fkey_func)(char *str,/* string currently entered */
int key, /* key that was pressed */
int pos, /* position number of current
character being processed */
int *newposptr) /* pointer to new position */
The prototype to the undef_akey_func is similar to the one above.
The str is a pointer to a null-terminated string of characters that has been
currently entered. For instance, if the string currently entered is
ABC123
str will point to "ABC123".
The second argument is the last key that was pressed. You should use the
values defined in the header file "keycodes.h" if you want to check for
non-ascii keys. This will ensure that you are properly checking the
keystroke desired. For instance, if you want to check if the key pressed was
the Page Up key, use the constant PGUP defined in keycodes.h.
Page 104 The C Window Library Page 104
The third argument is an integer representing the position number of the
current character that the cursor is on. The first character is at position
number 0, the second character in the input field is 1, etc. If there is an
input mask (as in WindowGetMaskString() and WindowGetMaskStringAttr()) the
position number does not include any characters that are used to create the
non-input positions. For instance:
"__/__/__ "
01 23 45
The numbers under the mask are the position numbers for each character.
The fourth argument is a pointer to an integer representing a new position
to move the cursor. Use of this pointer will be explained later.
for this argument will be made evident later. The reason for the third
argument being a pointer rather than an integer will be evident later on.
Specifying when to call an undefined key function in a Regular Expression
-------------------------------------------------------------------------
An empty bracketed simple regular expression tells the input manager to call
the undefined keystroke function. An example of this type of regular
expression is as follows:
Regular Definition
Expression ----------
----------
[A-Z][] The first input position must be btween 'A'
and 'Z', and the second position will
automatically call the user defined undefined
keystroke function.
20[] All twenty input positions will call the
undefined keystroke function.
3[0-9]2[]2[A-Z] The first three input positions must be
between '0' and '9', the next two input
positions automatically call the undefined
keystroke function, and the last two
positions must be between 'A' and 'Z'.
If you use this form of a regular expression, you MUST have defined an
undefined keystroke function. If you did not define one, you will more than
likely get into an infinite loop. Using this form of regular expression
combined with the return values (defined below) that can be returned to the
input manager, you will virtually have total control of the way the input is
handled.
Page 105 The C Window Library Page 105
Return Values To The Input Manager
----------------------------------
When writing your function you must return an integer to the input manager.
This integer will inform the input manager as to what action to take. Here
are a list of the return values and what they inform the input manager:
Return Action to
Value Take
------ ---------
DONT_PROCESS Do not Process keystroke and continue getting
input.
MOVE_CURSOR_LEFT Move cursor left.
MOVE_CURSOR_RIGHT Move cursor right.
DELETE_AT_CURSOR Delete character at cursor.
TOGGLE_INSERT Toggle Insert/Overwrite mode.
DESTRUCT_BACKSPACE Destructive Backspace.
ACCEPT_INPUT Accept Input and return string.
ACCEPT_DEFAULT Accept default string and return.
ERASE_INPUT Erase Input and go to first character in input field.
GOTO_FIRST Go to first input character in field.
GOTO_LAST Move cursor to last input character in field.
MOVE_TO_CHARACTER Move cursor to input position specified in the *pos
argument.
INSERT_CHARACTER Accept character as valid and insert it at the
current cursor position.
The MOVE_TO_CHARACTER return value moves the input cursor to the position in
the input string specified in the fourth argument of undef_akey_func or
undef_fkey_func. If you recall, the fourth argument was a pointer to an
integer.
The INSERT_CHARACTER return value only applies to the function pointed to by
undef_akey_func.
These user-defined functions can do anything, not just process keystrokes.
For instance, if you want F1 to be a help key, where the help function is
in a function called do_help() you must make sure that:
a) the F1 key is undefined (not defined in the window_edit_key array)
b) the undef_fkey_func function pointer points to your function
c) return an integer to the input manager from your function.
Here is a typical way that this would be set up:
Page 106 The C Window Library Page 106
#include "window.h"
/* ... Other #includes and #defines */
int do_help(); /* define help function */
main()
{
WindowInitializeSystem();
/* ...Some code */
undef_fkey_func = do_help; /* point function pointer to do_help */
WindowGetString(/* ... Parameters */); /* call input function */
/* ... Other code */
}
int do_help(char *str, int ch, int pos, int *newpos)
{
if (ch == F1) /* check for F1 */
{
/* help function goes here */
return DONT_PROCESS; /* make sure input manager does not process this
or any other undefined keystroke */
}
else
{
*newpos = 3; /* move input cursor to the third input position */
return MOVE_TO_CHARACTER; /* let input manager know we want to move the
input cursor */
}
}
With this flexibility in the input functions, you can totally control how
input is handled.
Page 107 The C Window Library Page 107
INPUT OPTIONS
-------------
In the previous examples, the available options were discussed briefly.
These options provide further control of the input functions. Here is a list
of the options that are available:
Option Definition
------ ----------
UPPERCASE Translates and displays lower case to upper
case.
LOWERCASE Translates and displays upper case to lower
case.
CHECKSPACES Spaces are counted when determining whether
the minimum number of characters are entered.
ENHANCEDKEY Use the enhanced keyboard keys and
distinguish between keypad keys and separate
cursor pad keys. Also detect F11 and F12 keys.
CHECKREGEXP Check to see if all characters entered agree
with the regular expression provided.
AUTORETURN Automatically accept the input when a character
in the last input position is entered.
HOMECURSOR Move scrolled input back to the first
character in the input string when input is
accepted.
CLEARFIELD Clears the input field if the first key pressed
is recognized by the regular expression as a
valid input key. If a cursor movement key is
pressed first, the field is not cleared if any
subsequent input keys are pressed.
USEMOUSE Utilize the mouse to move the cursor in the
input field.
NO_OPTIONS No options desired.
UPPERCASE
---------
The UPPERCASE option converts and displays all lower case letters to upper
case while the user is inputting characters.
Page 108 The C Window Library Page 108
LOWERCASE
---------
The LOWERCASE option converts and displays all upper case letters to lower
case while the user is inputting characters.
CHECKSPACES
-----------
The CHECKSPACES option will cause the input manager to count any embedded
spaces when determining whether the minimum number of characters are reached.
Trailing spaces are counted only if the user explicitly put them there.
ENHANCEDKEY
-----------
The ENHANCEDKEY option will distinguish between the cursor keys on the keypad
from the dedicated cursor keys on the enhanced keyboards as well as the Ins,
Home, Del, PgUp and PgDn keys. Also the F11 and F12 keys will be detected.
CHECKREGEXP and the reg_exp_error_func function pointer
-------------------------------------------------------
The CHECKREGEXP option will check to make sure that every character inputted
is a valid character according to the regular expression. When inserting or
deleting characters during input, characters may be moved left or right
depending on whether the input is in insert or overwrite mode. When the
characters are moved, the resulting pattern of characters may not match the
regular expression desired. For instance, if the regular expression is
"3[A-Z]2[0-9]", meaning 3 characters between A and Z followed by 2 characters
between 0 and 9, and the current input entered is as follows :
ABC34
If the cursor is currently under the 'C', the delete key is pressed, and
the input is currently in insert mode, the '34' will be moved one character to
the left. The resulting input would then look like this:
AB34
As you can see, the input does not match the regular expression "3[A-Z]2[0-9]"
because the '3' is in a position that should be occupied by a letter. When
the CHECKREGEXP option is chosen, each position is checked when the user wants
to accept the string, not while the user is entering characters. If the
input is not OK, the input manager will not accept the string. You can
override this by setting the reg_exp_error_func function pointer.
The global function pointer reg_exp_error_func is prototyped as follows:
int (*reg_exp_error_func)(char *buf, int nomatch);
Page 109 The C Window Library Page 109
where buf is the current string entered, and nomatch is the position of the
first non-matching character that did not match the regular expression. The
first character of the string is at position 0.
Your function must return an integer back as to what to do. There are two
valid return values, namely ACCEPT_INPUT and DONT_PROCESS. A return value of
ACCEPT_INPUT will accept the input, even though all of the characters do not
match the regular expression. DONT_PROCESS tells the input manager to keep
getting input. Here is an example:
int my_check_func();
main()
{
...
reg_exp_error_func = my_check_func;
WindowGetString(other parameters, CHECKREGEXP,"[A-Z][0-9]");
...
}
int my_check_func(char *buf, int mistake_pos)
{
/* Assume w is initialized and open for writing */
WindowPrintf(w,
"Illegal input for %s. Illegal character at position %d",buf,
mistake_pos);
GET_KEY();
WindowHide(w,NOEFFECT);
return DONT_PROCESS;
}
The above example shows a function called my_check_func() which will be
called when the input manager detects that all of the characters in the
buffer buf do not match the regular expression. The function displays a
message in a window and waits for a key to be pressed. Then the function
returns DONT_PROCESS back to the input manager.
AUTORETURN
----------
The AUTORETURN will automatically accept the input and return to the calling
function if the cursor is on the last input position and the user types a
valid character. Of course, if CHECKREGEXP is on, the input is checked for
validity.
Page 110 The C Window Library Page 110
HOMECURSOR
----------
The HOMECURSOR options will scroll an input field back to the first position
when the input is accepted.
CLEARFIELD
----------
The CLEARFIELD option will automatically clear the input field of any
characters if the first key struck is a key recognized as a valid input key,
and the character is displayed in the input position. If the first key
struck is a cursor movement key or a delete character key (destructive
backspace or delete character), any valid input key that is subsequently
struck does not clear the field, but is recorded in the input field.
USEMOUSE
--------
This option can only be used if you have access to The C Window Library
MouseLib functions, the system has a mouse installed, and the mouse has been
activated. By positioning the mouse cursor to any valid input position in
the input field and pressing the mouse button defined in the global integer
variable field_button_press, the cursor is automatically moved to that input
position. If the CLEARFIELD option is used in conjunction to USEMOUSE, any
subsequent input will not clear the field if the mouse was used to move the
cursor.
NO_OPTIONS
----------
No field options desired. In other words, all of the options defined above
are turned off.
Examples of Input Options
-------------------------
Examples:
a) WindowGetString(w,1,1,str,' ',1,1,UPPERCASE,"[YyNn]");
b) WindowGetString(w,1,1,str,' ',1,1,LOWERCASE,"[YyNn]");
c) WindowGetStringAttr(w,2,1,str,' ',CREATE_VIDEO_ATTRIBUTE(black,white),1,
1,UPPERCASE | AUTORETURN,"[YyNn]");
Page 111 The C Window Library Page 111
d) WindowGetString(w,1,1,str,' ',10,10,UPPERCASE | ENHANCEDKEY,"10.");
e) WindowGetString(w,1,1,str,' ',20,10,CHECKREGEXP |
HOMECURSOR,"10[A-Z]10[0-9]");
Example a) gets one character and will automatically set this character to
upper case.
b) same as a) except character is converted to lower case.
c) converts one character to uppercase and automatically accepts the
input because the input cursor was on the last input position.
Note the use of the bitwise OR (|) to set multiple options.
d) Converts the input to uppercase and treats extra keys on an
enhanced keyboard as different than their "normal" keys.
e) On accepting of the input field, the input is checked to see if
every position on the input field is checked to see if it matches
the regular expression. Once the input is accepted, the input is
scrolled back to the first input position.
THE num_chars_entered_func FUNCTION POINTER
-------------------------------------------
If the number of characters entered is not enough to satisfy the minimum
number of characters allowed, by default the input manager will not return
until the required number of characters is entered. However, a global
function pointer can be assigned to a user-written function that will
be called when the input manager detects that the minimum number of
characters was not reached. The function pointer num_chars_entered_func is
prototyped as follows:
int (*num_chars_entered_func)(char *buf, int minchars);
where buf is the current string that is entered, and minchars is the minimum
number of characters to expect.
Your function must return an integer back as to what to do. There are two
valid return values, namely ACCEPT_INPUT and DONT_PROCESS. A return value of
ACCEPT_INPUT will accept the input, even though the minimum number of
characters was not reached. DONT_PROCESS tells the input manager to keep
getting input. Here is an example:
int my_min_func();
main()
{
...
num_chars_entered_func = my_min_func;
...
}
Page 112 The C Window Library Page 112
int my_min_func(char *buf, int m)
{
/* Assume w is initialized and open for writing */
WindowWriteString(w,"Not enough characters!",1,1);
GET_KEY();
WindowHide(w,NOEFFECT);
return DONT_PROCESS;
}
The above example shows a function called my_min_func() which will be called
when the input manager detects that the number of characters in the buffer
buf, does not meet the minimum requirements. The function displays a message
in a window and waits for a key to be pressed. Then the function returns
DONT_PROCESS back to the input manager.
OTHER INPUT RELATED FUNCTIONS
-----------------------------
There are other input related functions that you can use to translate strings
into their character mask equivalents and vice-versa.
TranslateStringToMaskString()
-----------------------------
This TranslateStringToMaskString() function takes a string and either places
spaces, or the actual mask character between the characters in the string. A
pointer to the translated string is returned. Here is the prototype:
char *TranslateStringToMaskString(char *buffer, char *mask, char *buf2,
int maskchar, int flag)
The first argument is a pointer to the string to translate. The second
argument is the mask string to use. The third argument is a pointer to the
buffer that will store the translated string. The fourth argument is the
mask character that is to be used. This character determines where the input
positions are. The flag argument tells whether to include spaces between
each component, or to use the character in the mask.
You must make sure that buf2 is big enough to hold the translated string.
The string length of the mask determines how far to translate the string. If
the mask string is shorter than the string to translate, the string is
truncated up to the last character in the mask. If the string to translate
runs out of characters before the mask has been totally scanned, the extra
characters in buf2 will either be spaces, or the characters in the mask (not
the mask character specified in argument 4) will be copied over.
Page 113 The C Window Library Page 113
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define DATEMASK "__/__/__"
char buf1[] = "123456";
char buf2[9];
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',0);
WindowPrintf(w,
"The original string is %s\nThe translated string is %s\n",
buf1,buf2);
TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',1);
WindowPrintf(w,
"The original string is %s\nThe translated string is %s\n",
buf1,buf2);
}
The example above takes the string "123456" with the mask of "__/__/__". The
results of a translate with a flag of 0, and with a flag value of 1, is
displayed in window w.
The return value for TranslateStringToMaskString() is the pointer to the
buffer that holds the translated string. This string is automatically null
terminated.
TranslateMaskStringToString()
-----------------------------
This TranslateMaskStringToString() function does the opposite of
TranslateStringToMaskString(). This function takes a string that has been
translated with the TranslateStringToMaskString() or contains mask characters
and returns the string without the extra characters. Here is the prototype:
char *TranslateMaskStringToString(char *buffer, char *mask, char *buf2,
int maskchar)
The first argument is a pointer to the translated string. The second argument
is the mask string to use. The third argument is a pointer to the buffer that
will store the resulting string. The fourth argument is the mask character
that is to be used. This character determines where the input positions are.
Page 114 The C Window Library Page 114
You must make sure that buf2 is big enough to hold the new string.
The translation stops when either the end of the buffer is reached, or the end
of the mask string is reached.
Example:
#include "window.h"
#include <string.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define DATEMASK "__/__/__"
char buf1[] = "12/34/56";
char buf2[9];
WPOINTER w;
main()
{
memset(buf2,0,sizeof(buf2));
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
TranslateMaskStringToString(buf1,DATEMASK,buf2,'_');
WindowPrintf(w,"The original string is %s\n"
"The untranslated string is %s\n", buf1,buf2);
}
The example above takes the string "12/34/56" with the mask of "__/__/__".
The results of the translation is displayed in window w.
The return value for TranslateMaskStringToString() is the pointer to the
buffer that holds the translated string. This string is automatically null
terminated.
Page 115 The C Window Library Page 115
VIRTUAL WINDOWS
---------------
A virtual window can be thought of as a rectangular area filled with text.
This rectangular region can be broken up into rows and columns, just as a
normal window can be divided into rows and columns. The differences between
a virtual window and a regular window is that a virtual window's dimensions
can be larger than the physical screen, and a virtual window is not displayed
on the screen. Then what good is it if you cannot display it? You use
regular windows to display portions of the virtual window. If a regular
window is used to view a virtual window, the regular window is called a
viewport. With this method, you can use a viewport to display a virtual
window, and then 'pan' around, viewing different sections of the virtual
window. Text editors use this method to display files. Scrolling popup
menus also use virtual windows.
With The C Window Library, you can create virtual windows of any size, up to
available user memory. You can have a maximum of 256 virtual windows defined
at the same time.
Using Windows as Viewports
--------------------------
If text is written to a virtual window, and there is a viewport that is
displaying the portion of the virtual window that has changed, the viewport
will show the change immediately. You do not have to "repaint" or "refresh"
the viewport to show an updated change. That is handled internally in The C
Window Library. However, there is an option that will "freeze" a viewport,
i.e. will not update automatically, if there is a change in the virtual
window. When the viewport is unfrozen, the changes to the virtual window are
than displayed.
Attributed and Non-Attributed Virtual Windows
---------------------------------------------
There are two types of virtual windows. You can have either a virtual window
with its own video attributes or a virtual window which gets its video
attributes from the viewport that is displaying the virtual window.
Virtual windows without attributes use half as much memory as a virtual
window with attributes, but attributed virtual window's are more flexible.
For instance, lets say you have highlighted some text in the virtual window.
If the virtual window is not attributed, you must write the highlight
attribute to the viewport window using one of the window functions
(WindowWriteStringAttr() for example), since the virtual window does not have
the capacity to store the video attribute. If you were to scroll the
highlighted portion out of the viewport, you lose the highlight attribute,
and must call the window function again to highlight the text, if the text is
displayed again in the viewport. With an attributed virtual window, you
Page 116 The C Window Library Page 116
write the attributes to the virtual window. Since the attributes are stored
in the virtual window structure itself, the attributes are retained until you
change them.
From this point on, virtual windows without attributes are called NOATTRIBUTE
virtual windows. Virtual windows with attributes will be called ATTRIBUTE
virtual windows.
Virtual Window's Logical Cursor
-------------------------------
Each virtual window has its own logical cursor. This cursor is updated
automatically when calling VirtualPrintf(), and VirtualWriteCharacter()
functions, or can be updated manually by calling the VirtualMoveCursor()
function. This cursor is independent of the screen cursor.
Page 117 The C Window Library Page 117
CREATING VIRTUAL WINDOWS
------------------------
The section will discuss creating virtual windows using the
VirtualInitialize() function.
VirtualInitialize()
-------------------
Virtual windows are created by calling the VirtualInitialize() function.
Here is the prototype:
VWPOINTER VirtualInitialize(int vwtype, unsigned nrows, unsigned ncols,
int attr)
The VirtualInitialize() function returns a pointer to a virtual window
structure (a VWPOINTER). The first argument to VirtualInitialize() tells
whether the virtual window will or will not have its own video attributes.
If this argument is NOATTRIBUTE, the virtual window will not have attributes,
otherwise if it is ATTRIBUTE, the virtual window will have its own
attributes. The second argument is the number of rows of the virtual window.
The third argument is the number of columns. The fourth argument is the
attribute to use for the virtual window. This argument is ignored if the
virtual window is NOATTRIBUTE.
Example:
#include "window.h"
#include <stdio.h>
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw1, /* virtual window pointers */
vw2;
main()
{
WindowInitializeSystem();
/* set up a NOATTRIBUTE virtual window */
vw1 = VirtualInitialize(NOATTRIBUTE, /* virtual window type */
30, /* Number of rows */
80, /* Number of cols */
0); /* Attribute */
/* set up an ATTRIBUTE virtual window */
vw2 = VirtualInitialize(ATTRIBUTE, /* virtual window type */
30, /* Number of rows */
100, /* Number of cols */
NORM); /* Attribute */
if (vw1 == (VWPOINTER)0 ||
vw2 == (VWPOINTER)0 ) /* Check if allocation worked */
printf("Error in allocating virtual window. The error number is %d",
window_error_code);
}
Page 118 The C Window Library Page 118
In the above program, the VirtualInitialize() function is called. This
function allocates memory for the virtual window, and does other
initializations. Once this function is called, you can write to and read
characters from the virtual window.
Notice that the first argument to VirtualInitialize() is either the constant
NOATTRIBUTE or ATTRIBUTE.
Also note that there is a check to see whether the virtual windows could be
allocated. If there are no errors, VirtualInitialize() returns a valid
VWPOINTER. If there are errors, VirtualInitialize() returns a null VWPOINTER
and sets the global variable window_error_code to one of the following:
NO_HEAP_MEM if there is not enough memory to allocate for the virtual window.
MAX_V_WINDOW if there are already 256 virtual windows defined.
Page 119 The C Window Library Page 119
ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS
-----------------------------------------
For a virtual window to have any useful purpose, it should be displayed on
the screen. However the virtual window may be larger than the physical
screen. The problem is solved by using normal windows to display parts of
the virtual window.
WindowAssignToVirtual()
-----------------------
To turn a window into a viewport onto a virtual window, you use the
WindowAssignToVirtual() function.
Here is the prototype:
int WindowAssignToVirtual(WPOINTER w, VWPOINTER vw, unsigned row,
unsigned col)
The first argument is the window that will be turned into a viewport. The
second argument is the virtual window that w will be assigned to. The third
and fourth arguments are the (row,col) of the virtual window. This position
is where the upper left hand corner of the viewport's text area will be
placed.
To illustrate this, here is a sample call to WindowAssignToVirtual():
WindowAssignToVirtual(w,vw,5,10)
The following description shows how this is to be interpreted:
VIRTUAL WINDOW
-------------------------------------------------------------------
|(1,1) (100,1)|
| |
| (5,10) of the virtual window is equivalent to (1,1) of |
| | the viewport. |
| v |
| ----------------------- |
| |(1,1) of the viewport| |
| | | |
| | VIEWPORT WINDOW | |
| |(14,1) (14,30)| |
| ----------------------- |
| |
|(100,1) (100,100) |
--------------------------------------------------------------------
The viewport relative position of (1,1) is located at (5,10) of the virtual
window.
Page 120 The C Window Library Page 120
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);/* Write string to virtual
window */
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual
window */
}
The above program opens a virtual window, vw, and opens a normal window, w.
In the above example, the VirtualWriteString() function is used to write
strings to the virtual window. See the WRITING TEXT TO VIRTUAL WINDOWS
section for more information on VirtualWriteString().
Once a window is turned into a viewport, nothing is stopping you from using
the other window functions. You can still use WindowWriteString(),
WindowMove(), WindowPrintf(), etc. Writing text to a viewport window via the
normal window functions does not effect the virtual window in any way.
If there are no errors, WindowAssignToVirtual() returns NO_ERROR.
If there are errors, WindowAssignToVirtual() returns the following values:
BAD_WINDOW if the window does not exist.
BAD_V_WINDOW if the virtual window does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()).
Out of bounds Coordinates
-------------------------
The next question is "What do you do if the coordinates given in
WindowAssignToVirtual() are out of bounds of the range of the virtual
window?". For instance, if the virtual window has 100 rows, but the call to
WindowAssignToVirtual() specifies row 97, and the viewport itself has a
height of 10 rows. The window manager will fill the viewport with as much of
the virtual window as possible, and will clear the contents of the viewport
that are not inside the virtual window.
Here is another view of what happens in this case:
Page 121 The C Window Library Page 121
VIRTUAL WINDOW
-------------------------------------------------------------------
|(1,1) (100,1)|
| |
| (97,10) of the virtual window is the same as (1,1) of |
| | the viewport window. |
| v |
| ----------------------- |
| |(1,1) of the viewport| |
| | | |
|(100,1) | VIEWPORT WINDOW | (100,100) |
--------------------------------------------------------------------
|This portion of the |
| window is cleared |
-----------------------
The above picture shows a viewport that is partially contained in the virtual
window. The contents of the window above the last row of the virtual window
is updated, while the portion of the viewport below the line is cleared.
WindowCloseViewport()
---------------------
To turn a viewport back to a normal window, WindowCloseViewport() is called.
Here is the prototype:
int WindowCloseViewport(WPOINTER w, int hide, int effect)
where w is the viewport to be turned back into a regular window. When this
function is called, the window w is cleared with its own video attribute.
The second argument tells if the window is to be hidden. If hide is 1, the
window is hidden. If it is 0, the window remains on the screen. The effect
argument is a special effect to use when hiding the window. A list of
special effects are defined in the DISPLAYING WINDOWS section. This function
DOES NOT close the virtual window or does a WindowClose() to the viewport
window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
Page 122 The C Window Library Page 122
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);/* Write string to virtual
window */
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual
window */
GET_KEY();
WindowCloseViewport(w,1,NOEFFECT);
GETKEY();
}
The example above opens a virtual windows and a normal. It then assigns the
windows to the virtual window by calling WindowAssignToVirtual(). The
program then unassigns the viewport by calling WindowCloseViewport().
If there are no errors, WindowCloseViewport() returns NO_ERROR.
If there are errors, WindowCloseViewport() returns the following values:
BAD_WINDOW if the window does not exist.
BAD_V_WINDOW if the virtual window that w is a viewport on does not exist.
WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()).
Page 123 The C Window Library Page 123
WRITING TEXT TO VIRTUAL WINDOWS
-------------------------------
There are several functions that write strings to virtual windows. They are
divided into two groups: functions that take null terminated strings as
arguments, and functions that use character buffers and a length argument.
When any of the text functions are called, any viewport that is displaying
any portion of the virtual window that has been changed will display the
update.
Null Terminated String Functions
--------------------------------
VirtualWriteString()
--------------------
The VirtualWriteString() function writes a null terminated to a virtual
window at a specific row and column of the virtual window. Here is the
prototype:
int VirtualWriteString(VWPOINTER vw, char *string, unsigned row,
unsigned col)
The first argument is the virtual window pointer. The second argument is the
string to write. The third and fourth arguments are the row and column of
the virtual window that the string is to be written to. If the string will
exceed the boundaries of the virtual window, the string is truncated.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w1, w2;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w1 = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX);
w2 = WindowInitialize(BORDER,13,1,20,10,NORM,NORM,DOUBLEBOX);
WindowOpen(w1);
WindowOpen(w2);
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);/* Write string to virtual
window */
WindowAssignToVirtual(w1,vw,1,1); /* Assign viewport to virtual window */
WindowAssignToVirtual(w2,vw,1,10); /* Assign viewport to virtual
window */
}
Page 124 The C Window Library Page 124
The example above writes the string "This is a string" to the virtual window
at row 1, column 1. The windows w1 and w2 are viewports on the virtual
window vw. The window w1 is located at (1,1) of the virtual window, while w2
is located at (1,10) of the virtual window. The window w1 will display "This
is a string", but w2 will only display "string" since it is situated at
column 10 of the virtual window.
If there are no errors, VirtualWriteString() returns NO_ERROR.
If there are errors, VirtualWriteString() returns the following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the either row or col is out of bounds of the virtual
window.
VirtualWriteStringAttr()
------------------------
The VirtualWriteStringAttr() works the same way as the VirtualWriteString()
except that a video attribute is used. Here is the prototype:
int VirtualWriteStringAttr(VWPOINTER vw, char *string, unsigned row,
unsigned col, int attr)
The last argument is the video attribute to use. If the virtual window is
NOATTRIBUTE, the attribute is ignored, and only the string is written. Any
viewports that are assigned to NOATTRIBUTE virtual windows will not reflect
the change in the attribute.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringAttr(vw,"This is a string",1,1,REVERSE);
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual window */
}
Page 125 The C Window Library Page 125
The example above writes the string "This is a string" in the virtual window
with a video attribute defined by the constant REVERSE.
If there are no errors, VirtualWriteStringAttr() returns NO_ERROR.
If there are errors, VirtualWriteStringAttr() returns the following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the either row or col is out of bounds of the virtual
window.
NO_ATTRIB if the virtual window is NOATTRIBUTE. If this error occurs,
only the string is written.
VirtualWriteCenterString()
--------------------------
The VirtualWriteCenterString() writes a centered string in a virtual window.
Here is the prototype:
int VirtualWriteCenterString(VWPOINTER vw, char *string, unsigned row)
The row argument is the row to center the string on.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteCenterString(vw,"This is a string",1);
WindowAssignToVirtual(w,vw,1,1);
}
Page 126 The C Window Library Page 126
The above example illustrates the use of VirtualWriteCenterString(). The
viewport window w is just used as a guide to display what has happened.
If there are no errors, VirtualWriteCenterString() returns NO_ERROR.
If there are errors, VirtualWriteCenterString() returns the following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row is out of bounds of the virtual window.
VirtualWriteCenterStringAttr()
------------------------------
The VirtualWriteCenterStringAttr() function works the same way as
VirtualWriteCenterString() except that a video attribute is specified. Here
is the prototype:
int VirtualWriteCenterStringAttr(VWPOINTER vw, char *string, unsigned row,
int attr)
The attr argument is the video attribute to use. If the virtual window is
NOATTRIBUTE, the attribute is ignored and only the string is written to the
virtual window.
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteCenterStringAttr(vw,"This is a string",1,REVERSE);
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual window */
}
Page 127 The C Window Library Page 127
If there are no errors, VirtualWriteCenterStringAttr() returns NO_ERROR.
If there are errors, VirtualWriteCenterStringAttr() returns the following
values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row is out of bounds of the virtual window.
NO_ATTRIB if the virtual window is NOATTRIBUTE. If this error occurs,
only the string is written.
VirtualWriteStringCC()
----------------------
The VirtualWriteStringCC() function centers and writes a string around a
column of the virtual window (the CC stands for Centered Column). If the
string is longer than the width of the virtual window, the string is placed
on column 1 is clipped at the right edge of the virtual window.
Here is the prototype:
int VirtualWriteStringCC(VWPOINTER vw, char *string, unsigned row,
unsigned col)
The first argument is the window. The second argument is the string. The
third argument is the row to write the string, and the last argument is the
column to center the string on.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringCC(vw,"This",1,10);
VirtualWriteStringCC(vw,"is",2,10);
VirtualWriteStringCC(vw,"centered",3,10);
VirtualWriteStringCC(vw,"around",4,10);
VirtualWriteStringCC(vw,"column",5,10);
VirtualWriteStringCC(vw,"10",6,10);
WindowAssignToVirtual(w,vw,1,1);
}
Page 128 The C Window Library Page 128
The example above writes the text centered around column 10 of the virtual
window w.
The return values for VirtualWriteStringCC() are the same as
VirtualWriteString().
VirtualWriteStringCCAttr()
--------------------------
The VirtualWriteStringCCAttr() works the same way as the
VirtualWriteStringCC() function except that a video attribute is specified.
Here is the prototype:
int VirtualWriteStringCCAttr(VWPOINTER vw, char *string, unsigned row,
unsigned col, int attr)
The attribute to use is the last argument. If the virtual window is
NOATTRIBUTE, the attr argument is ignored, and only the string is written
to the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringCCAttr(vw,"This",1,10,REVERSE);
VirtualWriteStringCCAttr(vw,"is",2,10,REVERSE);
VirtualWriteStringCCAttr(vw,"centered",3,10,REVERSE);
VirtualWriteStringCCAttr(vw,"around",4,10,REVERSE);
VirtualWriteStringCCAttr(vw,"column",5,10,REVERSE);
VirtualWriteStringCCAttr(vw,"10",6,10,REVERSE);
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteStringCCAttr() are the same as
VirtualWriteStringAttr().
Page 129 The C Window Library Page 129
VirtualWriteStringRJ()
----------------------
The VirtualWriteStringRJ() function writes a right justified string in a
virtual window. Here is the prototype:
int VirtualWriteStringRJ(WPOINTER w, char *string, unsigned row,
unsigned col)
The first argument is the virtual window. The second argument is the string.
The third argument is the row to write the string, and the last argument is
the column to place the right edge of the string.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringRJ(vw,"This",1,10);
VirtualWriteStringRJ(vw,"is",2,10);
VirtualWriteStringRJ(vw,"right",3,10);
VirtualWriteStringRJ(vw,"justified",4,10);
VirtualWriteStringRJ(vw,"on ",5,10);
VirtualWriteStringRJ(vw,"column",6,10);
VirtualWriteStringRJ(vw,"10",7,10);
WindowAssignToVirtual(w,vw,1,1);
}
The example above writes the text right justified on column 10 of the
virtual window.
The return values for VirtualWriteStringRJ() are the same as
VirtualWriteString().
Page 130 The C Window Library Page 130
VirtualWriteStringRJAttr()
--------------------------
The VirtualWriteStringRJAttr() writes a right justified string in a virtual
window, and allows you to specify a video attribute. Here is the prototype:
int VirtualWriteStringRJAttr(WPOINTER w, char *string, unsigned row,
unsigned col, int attr)
The last argument is the attribute to use.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
VWPOINTER vw; /* virtual window pointers */
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteStringRJAttr(vw,"This",1,10,REVERSE);
VirtualWriteStringRJAttr(vw,"is",2,10,REVERSE);
VirtualWriteStringRJAttr(vw,"right",3,10,REVERSE);
VirtualWriteStringRJAttr(vw,"justified",4,10,REVERSE);
VirtualWriteStringRJAttr(vw,"on ",5,10,REVERSE);
VirtualWriteStringRJAttr(vw,"column",6,10,REVERSE);
VirtualWriteStringRJAttr(vw,"10",7,10,REVERSE);
WindowAssignToVirtual(w,vw,1,1);
}
The example above writes the text right justified on column 10 of the
virtual window. If the virtual window is NOATTRIBUTE, only the string is
written.
The return values for VirtualWriteStringRJAttr() are the same as
VirtualWriteStringAttr().
Page 131 The C Window Library Page 131
Length Controlled Functions
---------------------------
VirtualWriteCharacters()
------------------------
The VirtualWriteCharacters() writes a specified number of characters from a
buffer to the virtual window. Here is the prototype:
int VirtualWriteCharacters(VWPOINTER vw, char *buffer, unsigned row,
unsigned col, unsigned length)
The first argument is the virtual window. The second argument is the buffer
where the characters are stored. The third and fourth arguments are the
(row,col) of where the characters will be placed in the virtual window. The
last argument is the number of characters from buffer that will be written.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
char buf[] = "Hello World!!";
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteCharacters(vw,buf,1,1,11); /* Writes "Hello World" */
VirtualWriteCharacters(vw,buf,2,1,13); /* Writes "Hello World!!" */
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteCharacters() are the same as
VirtualWriteString().
Page 132 The C Window Library Page 132
VirtualWriteAttributes()
------------------------
The VirtualWriteAttributes() writes a specified number of attributes from a
buffer to the virtual window. Here is the prototype:
int VirtualWriteAttributes(VWPOINTER vw, char *buffer, unsigned row,
unsigned col, unsigned length)
The first argument is the virtual window. The second argument is the buffer
where the attributes are stored. The third and fourth arguments are the
(row,col) of where the attributes will be placed in the virtual window. The
last argument is the number of attributes from buffer that will be written.
If the window is NOATTRIBUTE, this function does nothing.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
char buf[13];
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
for (i=0;i<13;i++)
if (i % 2)
buf[i] = NORM;
else
buf[i] = REVERSE;
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"Hello World!!",1,1);
VirtualWriteAttributes(vw,buf,1,1,13); /* Writes alternating NORM and
REVERSE attributes */
WindowAssignToVirtual(w,vw,1,1);
}
The return values for VirtualWriteAttributes() are the same as
VirtualWriteStringAttr().
Page 133 The C Window Library Page 133
VirtualWriteCharAndAttr()
-------------------------
The VirtualWriteCharAndAttr() function writes a string of character/attribute
pairs to a virtual window. Use this function if you have created a string of
character/attribute pairs, and want to output them easily. The string
consists of character and attributes in the following manner:
char-attr-char-attr...
Each character is followed by its corresponding video attribute.
Here is the prototype:
int VirtualWriteCharAndAttr(VWPOINTER vw, char *buffer, unsigned row,
unsigned col, unsigned length)
The first argument is the virtual window. The second is the buffer where the
character and attributes are stored. The third and fourth is the (row,col)
position in the virtual window to write, and the length argument is the
number of character/attribute pairs from the buffer to write. Please note
the difference in the meaning of the length argument in this function as
opposed to its use in the preceding functions.
If the virtual window is NOATTRIBUTE, nothing is written to the virtual
window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
char buf[26];
char *str = "Hello World!!";
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
for (i=0;i<26;i+=2,str++)
{
buf[i] = *str;
buf[i+1] = NORM;
}
VirtualWriteCharAndAttr(vw,buf,1,1,13);
WindowAssignToVirtual(w,vw,1,1);
}
Page 134 The C Window Library Page 134
The return values for VirtualWriteCharAndAttr() are the same as
VirtualWriteStringAttr().
VirtualWriteRepeatAttribute()
-----------------------------
The VirtualWriteRepeatAttribute() function writes an attribute a specified
number of times to a virtual window. Here is a prototype:
int VirtualWriteRepeatAttribute(VWPOINTER vw, int attr, unsigned row,
unsigned col, int count)
The attr argument is the attribute to use. The count argument specifies the
number of times to write the attribute attr to the virtual window starting at
(row,col). If the virtual window is NOATTRIBUTE, this function returns an
error.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteString(vw,"Hello World!!",1,1);
VirtualWriteRepeatAttribute(vw,REVERSE,1,1,13);
WindowAssignToVirtual(w,vw,1,1);
}
The example above illustrates that the VirtualWriteRepeatAttribute() writes
the REVERSE attribute 13 times starting at row 1, column 1 of the
virtual window w.
The return values for VirtualWriteRepeatAttribute() are the same as
VirtualWriteStringAttr().
Page 135 The C Window Library Page 135
VirtualWriteRepeatCharacter()
-----------------------------
The VirtualWriteRepeatCharacter() function writes a character a specified
number of times to a virtual window. Here is a prototype:
int VirtualWriteRepeatCharacter(WPOINTER w, int ch, int row, int col,
int count)
The count argument is the character to use. The count argument specifies the
number of times to write the character ch to the virtual window starting at
(row,col).
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
VirtualWriteRepeatCharacter(vw,'a',1,1,5);
VirtualWriteRepeatCharacter(vw,'b',2,1,5);
VirtualWriteRepeatCharacter(vw,'c',3,1,5);
WindowAssignToVirtual(w,vw,1,1);
}
The example above illustrates that the VirtualWriteRepeatCharacter() writes
the letter 'a', 'b', and 'c' 5 times on rows 1, 2, and 3 respectively.
The return values for VirtualWriteRepeatCharacter() are the same as
VirtualWriteString().
Page 136 The C Window Library Page 136
Formatted Write Functions
-------------------------
Format String
-------------
These functions write formatted output to virtual windows just like the
printf() function. There are two functions that do this, namely
VirtualPrintf() and VirtualPrintfAttr(). These functions use a format
string that is similar to the format string found in printf(). For example,
%d, %s, %lf, etc. and most of the escape sequences are supported. The list
of escape sequences supported are as follows:
\n - newline
\t - tab
\r - carriage return
\x - hexadecimal
Where Output is Placed
----------------------
The row and column of where the string will be written is determined by the
virtual window's logical cursor. The logical cursor is advanced by both of
these functions to one column position after the last character is printed.
If you want to start at a particular row and column of the window, you must
move the cursor yourself by calling the VirtualMoveCursor() function. This
function is explained in the MOVING THE LOGICAL CURSOR section.
When the virtual window is first initialized using VirtualInitialize(), the
logical cursor is automatically moved to (1,1) of the virtual window.
VirtualSetWrap()
----------------
With these functions, any text that will exceed the boundaries of the window
will be wrapped to the next line. If the output will exceed the last row of
the window, the window is automatically scrolled up by one line. This is the
default action to take when characters exceed the right edge of the
virtual window. If you want the output clipped instead of wrapped, you must
set the virtual window's wrap flag using the VirtualSetWrap() function.
The VirtualSetWrap() function sets the virtual window's wrap flag to either
on or off. Here is the prototype:
int VirtualSetWrap(VWPOINTER vw, int option)
The second argument will be 0 if you want to turn the wrap flag off, or 1 if
you want to turn it on. If the wrap flag is off, the output generated by
Page 137 The C Window Library Page 137
VirtualPrintf() and VirtualPrintfAttr() will be terminated when the right edge
of the window is reached. If the wrap flag is on, the output is wrapped to
the next line when the right edge is reached. Unlike regular windows, the
output is not scrolled if the last line of the virtual window is reached.
You can set the wrap flag to a virtual window at any time.
VirtualPrintf()
--------------
The VirtualPrintf() function writes formatted output to the virtual window.
Here is the prototype:
int VirtualPrintf(VWPOINTER vw, char *format [,arg1,...])
The first argument is the virtual window. The second argument is a format
string. The rest of the arguments are optional arguments that are written to
the virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
VirtualPrintf(vw,"3+2 is equal to %d\n",3+2);
GET_KEY();
VirtualPrintf(vw,"i is equal to %d\nj is equal to %lf\n",i,j);
}
The above example illustrates how VirtualPrintf() is used to print formatted
strings to a virtual window.
The return values for VirtualPrintf() are the same as VirtualWriteString().
Page 138 The C Window Library Page 138
VirtualPrintfAttr()
-------------------
The VirtualPrintfAttr() function writes formatted output to the virtual
window. The difference between VirtualPrintf() and VirtualPrintfAttr() is
that VirtualPrintfAttr() uses a video attribute specified as an argument.
Here is the prototype:
int VirtualPrintfAttr(VWPOINTER vw, int attr, char *format [,arg1,...])
The first argument is the virtual window. The second argument is the video
attribute to use. The third argument is the format string. The rest of the
arguments are optional arguments that are written to the virtual window.
If the virtual window is NOATTRIBUTE, only the string is written to the
window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
VirtualPrintfAttr(vw,REVERSE,"3+2 is equal to %d\n",3+2);
GET_KEY();
VirtualPrintfAttr(vw,REVERSE,"i is equal to %d\nj is equal to %lf\n",i,j);
}
The above example illustrates how VirtualPrintfAttr() is used to print
formatted strings.
The return values for VirtualPrintfAttr() are the same as
VirtualWriteStringAttr().
Page 139 The C Window Library Page 139
READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS
------------------------------------------------------
With The C Window Library, you can read the contents of a virtual window into
a character buffer. These functions provide the programmer with the contents
of the virtual window at any time. The functions to perform this are
VirtualReadAttributes(), VirtualReadCharacters() and VirtualReadCharAndAttr().
VirtualReadCharacters()
-----------------------
The VirtualReadCharacters() function reads the characters from a virtual
window into a buffer. Here is the prototype.
int VirtualReadCharacters(VWPOINTER vw, char *buffer, unsigned row,
unsigned col, unsigned length)
The first argument is the virtual window. The second argument is the buffer
to store the characters in. The third and fourth arguments are the (row,col)
position in the virtual window to start reading from. The last argument is
the number of characters to read.
You must make sure that buffer has enough room to hold all of the characters
read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM);
VirtualWriteString(vw,"Hello World!!",1,1);/* Write String */
VirtualReadCharacters(vw,buf,1,1,13); /* Read characters */
}
The example above illustrates the use of VirtualReadCharacters(), which reads
the virtual window's contents starting at (1,1). This happens to be the
string "Hello World!!".
If the length exceeds the right edge of the virtual window,
VirtualReadCharacters() will read up to the right edge of the virtual window.
Page 140 The C Window Library Page 140
If there are no errors, VirtualReadCharacters() returns NO_ERROR.
If there are errors, VirtualReadCharacters() returns one of the following:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row or column specified in the virtual window is out of
bounds.
VirtualReadAttributes()
----------------------
The VirtualReadAttributes() function reads the attributes from a virtual
window into a buffer. Here is the prototype.
int VirtualReadAttributes(VWPOINTER w, char *buffer, unsigned row,
unsigned col, unsigned length)
The first argument is the virtual window. The second argument is the buffer
to store the attributes in. The third and fourth arguments are the (row,col)
position in the virtual window to start reading from. The last argument is
the number of attributes to read. If the virtual window is NOATTRIBUTE,
nothing is read.
You must make sure that buffer has enough room to hold all of the attributes
read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
char buf[14] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,10,80,NORM);
VirtualReadAttributes(vw,buf,1,1,13); /* Read attributes */
}
The example above illustrates the use of VirtualReadAttributes(), which reads
the virtual window's attribute contents starting at (1,1) of the virtual
window.
Page 141 The C Window Library Page 141
If the length exceeds the right edge of the virtual window,
VirtualReadAttributes() will read up to the right edge of the virtual window.
If there are no errors, VirtualReadAttributes() returns NO_ERROR.
If there are errors, VirtualReadAttributes() returns one of the following:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row or column specified in the virtual window is out of
bounds.
NO_ATTRIB if the virtual window is NOATTRIBUTE.
VirtualReadCharAndAttr()
------------------------
The VirtualReadCharAndAttr() function reads character/attribute pairs from a
virtual window into a buffer. Here is the prototype.
int VirtualReadCharAndAttr(VWPOINTER w, char *buffer, unsigned row,
unsigned col, unsigned length)
The first argument is the virtual window. The second argument is the buffer
to store the character/attribute pairs in. The third and fourth arguments
are the (row,col) position in the virtual window to start reading from. The
last argument is the number of character/attribute pairs to read. If the
window is NOATTRIBUTE, nothing is read.
You must make sure that buffer has enough room to hold all of the
character/attribute pairs read in.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
char buf[27] = {0}; /* Null all elements of buf */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(ATTRIBUTE,10,80,NORM);
VirtualWriteString(vw,"Hello World!!",1,1);/* Write String */
VirtualReadCharAndAttr(vw,buf,1,1,13); /* Read character/attributes */
}
Page 142 The C Window Library Page 142
The example above illustrates the use of VirtualReadCharAndAttr(), which reads
the virtual window's character/attribute contents starting at (1,1) of the
virtual window. This happens to be the characters/attributes of the string
"Hello World!!".
If the length exceeds the right edge of the virtual window,
VirtualReadCharAndAttr() will read up to the right edge of the virtual window.
If there are no errors, VirtualReadCharAndAttr() returns NO_ERROR.
If there are errors, VirtualReadCharAndAttr() returns one of the following:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if the row or column specified in the virtual window is out of
bounds.
NO_ATTRIB if the virtual window is NOATTRIBUTE.
Page 143 The C Window Library Page 143
REPOSITIONING THE VIEWPORT
--------------------------
A viewport can be repositioned anywhere on the virtual window. This allows
to view different parts of the virtual window.
WindowPositionViewport()
------------------------
The WindowPositionViewport() function positions the viewport to a new
location on the virtual window it is associated with. Here is the prototype:
int WindowPositionViewport(WPOINTER w, unsigned row, unsigned col)
The first argument is the viewport window. The second argument and third
arguments are is the (row,col) position of the virtual window associated with
w. This position will be where the upper left hand corner of the viewport's
text area will be placed.
Example:
#include <stdio.h>
#include <string.h>
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
/* define filename characters */
#define FILENAMECHARS "25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]"
VWPOINTER vw; /* virtual window pointer */
WPOINTER w; /* Window pointer */
char filename[26];
FILE *infile; /* input file handle */
main()
{
unsigned int i,j,row,col;
WindowInitializeSystem();
WindowSaveInitial(0);
/* set up a Type 0 virtual window */
vw = VirtualInitialize(NOATTRIBUTE, /* virtual window type number */
200, /* Number of rows */
80, /* Number of cols */
0); /* Attribute */
Page 144 The C Window Library Page 144
/* set up viewport window */
w = WindowInitialize(BORDER,1,1,78,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
/* read a file name */
read_file();
/* display file in viewport */
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual window */
row = col = 1;
flush_keyboard_flag = TRUE; /* Set keyboard flush to TRUE */
while (1)
{
switch (GET_KEY()) /* Keep getting keys until ESCAPE key is hit */
{
case UARROW: /* Move viewport up 1 line */
if (row > 1)
WindowPositionViewport(w,--row,col);
break;
case DARROW: /* Move viewport down 1 line */
if (row < 189)
WindowPositionViewport(w,++row,col);
break;
case LARROW: /* Move viewport left 1 line */
if (col > 1)
WindowPositionViewport(w,row,--col);
break;
case RARROW: /* Move viewport right 1 line */
if (col < 69)
WindowPositionViewport(w,row,++col);
break;
case ESC: /* End program */
close_all();
break;
}
}
}
Page 145 The C Window Library Page 145
read_file() /* Gets a filename and displays it in the window */
{
int ch;
unsigned r = 1, c = 1;
filename[0] = 0;
WindowWriteString(w,"Please enter a file name: ",1,1);
WindowGetString(w,1,27,filename,'_',0,40,0,FILENAMECHARS);
if ((infile = fopen(filename,"r")) == NULL)
{
WindowMoveCursor(w,3,1);
WindowPrintf(w,"File name %s does not exist\nPress a key to continue",
filename);
GET_KEY();
close_all();
}
else
while(1) /* Read characters into virtual window */
{
ch = fgetc(infile);
if (feof(infile))
break;
if (ch != '\n')
VirtualWriteRepeatCharacter(vw,ch,r,c++,1);
else
{
r++;
c=1;
}
}
fclose(infile);
}
close_all()
{
WindowClose(w,NOEFFECT);
exit(0);
}
The above example reads in a text file and uses WindowPositionViewport() to
move left, right, up, or down. There is no checking to see if you have
scrolled past the end of the file.
The read_file() function reads a file and copies each character in the file to
the virtual window called vw.
In the main program, the global variable flush_keyboard_flag, defined in the
IMPORTANT GLOBAL VARIABLES section, is set to TRUE. When flush_keyboard is
TRUE, the keyboard buffer is flushed before any incoming keystrokes are
accepted. Otherwise the keyboard buffer is not flushed.
Page 146 The C Window Library Page 146
In the while(1) loop of the main program, the constants UARROW, DARROW,
LARROW, and RARROW, stands for the up, down, left, and the right arrow keys on
the keypad, respectively. The constants UARROW, DARROW, LARROW, and RARROW
are defined in keycodes.h. Depending on the key that is hit, the viewport is
repositioned to point to a new row or column. The call to
WindowPositionViewport() has three arguments. The first is the pointer to the
viewport window, the second and the third are the row and the column of the
virtual window to place the upper left hand corner of the viewport.
There is minimal bounds checking in the above example, however you can enhance
it by putting in more bounds checking and by implementing a page down, or page
up function.
If there are no errors, WindowPositionViewport() returns NO_ERROR.
If there are errors, WindowPositionViewport() will return one of the
following values:
BAD_WINDOW if the viewport window does not exist.
BAD_V_WINDOW if the viewport is pointing to a virtual window that does not
exist.
V_WINDOW_BOUND if the row and col arguments are out of bounds of the virtual
window.
Page 147 The C Window Library Page 147
SCROLLING THE VIEWPORTS
-----------------------
Viewports can have its display scrolled left, right, up, or down using the
WindowScrollViewport() function described below.
WindowScrollViewport()
---------------------
This functions scrolls the viewport specific number of characters.
Here is the prototype:
int WindowScrollViewport(WPOINTER w, unsigned num, int direction)
The first argument is the viewport and the second argument is the number of
characters to scroll. The last argument is the direction to scroll. This
direction can be UP, DOWN, LEFT, or RIGHT.
Example:
#include <stdio.h>
#include <string.h>
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
/* define filename characters */
#define FILENAMECHARS "25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]"
VWPOINTER vw; /* virtual window pointer */
WPOINTER w; /* Window pointer */
char filename[26];
FILE *infile; /* input file handle */
main()
{
unsigned int i,j,row,col;
WindowInitializeSystem();
WindowSaveInitial(0);
/* set up a Type 0 virtual window */
vw = VirtualInitialize(NOATTRIBUTE, /* virtual window type number */
200, /* Number of rows */
80, /* Number of cols */
0); /* Attribute */
/* set up viewport window */
w = WindowInitialize(BORDER,1,1,78,12,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
Page 148 The C Window Library Page 148
/* read a file name */
read_file();
/* display file in viewport */
WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual window */
flush_keyboard_flag = TRUE; /* Set keyboard flush to TRUE */
while (1)
{
switch (GET_KEY()) /* Keep getting keys until ESCAPE key is hit */
{
case UARROW: /* Move viewport up 1 line */
WindowScrollViewport(w,1,UP);
break;
case DARROW: /* Move viewport down 1 line */
WindowScrollViewport(w,1,DOWN);
break;
case LARROW: /* Move viewport left 1 line */
WindowScrollViewport(w,1,LEFT);
break;
case RARROW: /* Move viewport right 1 line */
WindowScrollViewport(w,1,RIGHT);
break;
case ESC: /* End program */
close_all();
break;
}
}
}
read_file() /* Gets a filename and displays it in the window */
{
int ch;
unsigned r = 1, c = 1;
filename[0]=0;
WindowWriteString(w,"Please enter a file name: ",1,1);
WindowGetString(w,1,27,filename,'_',0,40,0,FILENAMECHARS);
if ((infile = fopen(filename,"r")) == NULL)
{
WindowMoveCursor(w,3,1);
WindowPrintf(w,"File name %s does not exist\nPress a key to continue",
filename);
GET_KEY();
close_all();
}
else
while(1) /* Read characters into virtual window */
{
ch = fgetc(infile);
if (feof(infile))
break;
if (ch != '\n')
VirtualWriteRepeatCharacter(vw,ch,r,c++,1);
Page 149 The C Window Library Page 149
else
{
r++;
c=1;
}
}
fclose(infile);
}
close_all()
{
WindowClose(w,NOEFFECT);
exit(0);
}
The example above is the same as the example for the
WindowPositionViewport() function, except that the call to
WindowPositionViewport() is replaced with the appropriate
WindowScrollViewport() call.
For WindowScrollViewport(), the window is never scrolled if the scroll will
result in the upper left hand corner of the viewport being out of bounds of
the virtual window. For example, you cannot scroll left 1 character if the
viewport is located at (1,1) of the virtual window, similarly you cannot
scroll right if the virtual window has a maximum of 80 characters and the
upper left hand corner of the viewport is situated at (1,80). The same
restrictions apply for scrolling up and down.
If there are no errors, all of the WindowScrollViewport() functions will
return NO_ERROR.
If there are errors, these functions will return the following value:
V_WINDOW_BOUND if the scroll will cause the upper left hand position of the
viewport to be out of bounds.
Page 150 The C Window Library Page 150
WRITING VIRTUAL WINDOW CONTENTS TO A FILE
-----------------------------------------
The C Window Library allows you to print the contents of a virtual window
using the VirtualWriteTextToFile() function.
VirtualWriteTextToFile()
------------------------
The VirtualWriteTextToFile() function allows you to print the contents of a
virtual window to a file. Here is the prototype:
int VirtualWriteTextToFile(VWPOINTER vw, char *filename, int mode)
The first argument is the virtual window. The second argument is the file
name. This file can be any of the DOS filenames ("con", "prn", "aux", etc.).
The file specified by filename must be closed before calling
VirtualWriteTextToFile(), and the file handle is automatically closed before
exiting VirtualWriteTextToFile().
The last argument is the mode switch. If mode is 1, a newline ('\n') is
written to the file after each line of the virtual window written to the
file. If mode is 0, no newline character is written. When mode 0 is chosen,
the file is open in binary mode, else it is open in text mode.
Example:
#include "window.h"
VWPOINTER vw;
char *filename = "wintext";
char *filename2 = "wintext2";
main()
{
int i;
WindowInitializeSystem();
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
VirtualWriteTextToFile(vw,filename,1); /* use newlines */
VirtualWriteTextToFile(vw,filename2,0); /* no newlines */
}
The example above illustrates two calls to VirtualWriteTextToFile(). The
first call writes the contents of the virtual window vw to a file called
"wintext". Note that the mode parameter for the first call is 1. This will
cause '\n' to be written to the file for each line of the virtual window.
The second call writes the virtual window text to a file call "wintest2",
with the mode parameter being 0 (no '\n').
Page 151 The C Window Library Page 151
Please note that VirtualWriteTextToFile() does not check if the file already
exists, so be careful that you do not replace files that are important to
you.
If there are no errors, VirtualWriteTextToFile() returns NO_ERROR.
If there are errors, VirtualWriteTextToFile() will return one of the
following:
BAD_V_WINDOW if the virtual window does not exist.
FILE_CANT_OPEN if the file specified by filename cannot be open.
FILE_CANT_CLOSE if the file specified by filename cannot be closed.
Page 152 The C Window Library Page 152
MOVING THE LOGICAL CURSOR
-------------------------
You can move and get the position of the logical cursor in a virtual window.
VirtualMoveCursor()
-------------------
The VirtualMoveCursor() function moves a virtual window's logical cursor to a
new location. Here is the prototype:
int VirtualMoveCursor(VWPOINTER vw, unsigned row, unsigned col)
The first argument is the virtual window, and the second and third arguments
denote the new (row,col) position of the logical cursor.
Example:
#include "window.h"
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
VirtualMoveCursor(vw,10,10); /* Moves the logical cursor to row 10, column
10 of the virtual window */
}
If there are no errors, VirtualMoveCursor() returns NO_ERROR.
If there are errors, VirtualMoveCursor() returns one of the following values:
BAD_V_WINDOW if the virtual window does not exist.
V_WINDOW_BOUND if either the row or column specified is out of bounds.
VirtualGetCursorPosition()
--------------------------
The VirtualGetCursorPosition() function gives the current row and column of
the cursor in a virtual window. Here is the prototype:
int VirtualGetCursorPosition(VWPOINTER vw, unsigned *row, unsigned *col)
The row and col arguments are pointers to unsigned integers that will contain
the row and column of the cursor after VirtualGetCursorPosition() is called.
Page 153 The C Window Library Page 153
Example:
#include "window.h"
VWPOINTER vw;
main()
{
unsigned row,col;
WindowInitializeSystem();
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
VirtualMoveCursor(vw,7,4);
VirtualGetCursorPosition(vw,&row,&col);
}
If there are no errors, VirtualGetCursorPosition() returns NO_ERROR.
If there are errors, VirtualGetCursorPosition() returns the following value:
BAD_V_WINDOW if the window does not exist.
Page 154 The C Window Library Page 154
CLEARING VIRTUAL WINDOWS
------------------------
The C Window Library contains functions that clears the entire virtual
window, or clears defined rectangular regions of the virtual window.
VirtualClear()
--------------
The VirtualClear() function clears an entire virtual window to spaces. Here
is the prototype:
int VirtualClear(VWPOINTER vw)
The only argument is the virtual window to clear.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClear(vw);
}
If there is no error, VirtualClear() returns NO_ERROR.
If there is an error, VirtualClear() returns the following values:
BAD_V_WINDOW if the virtual window does not exist.
Page 155 The C Window Library Page 155
VirtualClearAttr()
------------------
The VirtualClearAttr() function works the same way as the VirtualClear()
function except that an attribute is specified. Here is the prototype:
int VirtualClearAttr(VWPOINTER vw, int attr)
The second argument is the video attribute to use. If the virtual window is
NOATTRIBUTE, this function only clears the text.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClearAttr(vw,REVERSE);
}
The return values for VirtualClearAttr() are the same as VirtualClear(),
except for the following error:
NO_ATTRIB if the virtual window is NOATTRIBUTE.
VirtualClearRegion()
-------------------
The VirtualClearRegion() function clears a region of a virtual window. To
use the VirtualClearRegion() function, you must describe the rectangular
region to clear. Here is the prototype:
int VirtualClearRegion(VWPOINTER vw, unsigned urow, unsigned ucol,
unsigned lrow, unsigned lcol)
where (urow,ucol) describes the upper left of the rectangle and (lrow,lcol)
is the lower right of the virtual window.
Page 156 The C Window Library Page 156
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClearRegion(vw,4,4,8,15);
}
The VirtualClearRegion() call will clear the region described by the
rectangular coordinates (4,4) and (8,15).
If there is no error, VirtualClearRegion() returns NO_ERROR.
If there is an error, the VirtualClearRegion() function will return the
following values:
BAD_V_WINDOW if the VWPOINTER vw does not exist.
V_WINDOW_BOUND if the rectangular region defined is out of bounds of the
virtual window.
VirtualClearRegionAttr()
------------------------
The VirtualClearRegionAttr() function works the same as the
VirtualClearRegion() function, except that a video attribute is specified.
Here is the prototype:
int VirtualClearRegionAttr(VWPOINTER vw, unsigned urow, unsigned ucol,
unsigned lrow, unsigned lcol, int attr)
The attr argument is a video attribute to use to clear the region. If the
virtual window is NOATTRIBUTE, the attribute argument is ignored.
Page 157 The C Window Library Page 157
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
WPOINTER w;
VWPOINTER vw;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(ATTRIBUTE,30,80,NORM);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowAssignToVirtual(w,vw,1,1);
for (i=1;i<=10;i++)
VirtualWriteString(vw,"Hello World!!",i,1);
GET_KEY();
VirtualClearRegionAttr(vw,4,4,8,15,REVERSE);
}
The VirtualClearRegionAttr() call will clear the region described by the
rectangular coordinates (4,4) and (8,15) using the video attribute defined
by the constant REVERSE.
The VirtualClearRegionAttr() returns the same values as VirtualClearRegion()
with an additional error condition:
NO_ATTRIB if the virtual window is NOATTRIBUTE.
Page 158 The C Window Library Page 158
FREEZING VIEWPORTS
------------------
You can temporarily suspend or 'freeze' a viewport window from displaying
updates to the virtual window. This is good if there is data being written
to the virtual window which takes a long time to generate. The viewport can
be frozen when the information is being written, and unfrozen when the
writing of the data is terminated.
WindowFreeze()
--------------
The WindowFreeze() function suspends or resumes displaying of virtual window
updates on a viewport window. Here is the prototype:
int WindowFreeze(WPOINTER w, int option)
The first argument is the viewport window, and the second argument is the
option flag. If this flag is 0, the window is unfrozen, i.e. the window will
display virtual window updates. If it is 1, the window will suspend virtual
window updates from being displayed.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw;
WPOINTER w;
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM);
WindowOpen(w);
WindowAssignToVirtual(w,vw,1,1);
WindowDisplay(w,1,NOEFFECT);
/* Freeze Viewport */
WindowFreeze(w,1);
for (i=1;i<=10;i++)
{
delay(1000);
VirtualPrintf(vw,"Line %d\n",i);
}
/* Unfreeze window */
WindowFreeze(w,0);
GET_KEY();
Page 159 The C Window Library Page 159
/* Now try with window always displaying data */
VirtualClear(vw);
for (i=1;i<=10;i++)
{
delay(1000);
VirtualPrintf(vw,"Line %d\n",i);
}
}
The above program first freezes the viewport w with the first call to
WindowFreeze(). Then text is written slowly to the virtual window vw. This
text is not displayed until the window is unfrozen again with the second call
to WindowFreeze(). Everything is reset and the writing of the text to the
virtual window is done again, but this time the viewport is always displaying
virtual window updates, even when the text is being written to the virtual
window.
The delay() function is discussed in the TIMED DELAYS section.
If there is no error WindowFreeze() returns NO_ERROR.
If there are errors, WindowFreeze() returns one of the following values:
BAD_WINDOW if the viewport window does not exist.
BAD_V_WINDOW if the virtual window that the viewport is displaying does not
exist.
Page 160 The C Window Library Page 160
DISPOSING OF VIRTUAL WINDOWS
----------------------------
The last step is to dispose of the virtual window. The function to do this
is the VirtualFree() function.
VirtualFree()
-------------
The VirtualFree() function frees all the memory allocated to the virtual
window and destroys the virtual window pointer. Here is the prototype:
int VirtualFree(VWPOINTER vw, int hideflag, int effect)
The first argument is the virtual window. The second argument is a flag that
determines whether any viewports displaying the virtual window should be
hidden. If this argument is 1, all viewports displaying the virtual window
is hidden. If the argument is 0, all viewports are cleared, but not hidden.
The third argument is the special effect to use when hiding the viewports.
This argument is ignored if hideflag is 0. For a list of special effects,
refer to the DISPLAYING WINDOWS section.
Once VirtualFree() is called you must not use the VWPOINTER again unless you
assign it to another virtual window, or create a new virtual window.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
VWPOINTER vw; /* virtual window pointer */
WPOINTER w1, w2;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
vw = VirtualInitialize(NOATTRIBUTE,30,80,0);
w1 = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX);
w2 = WindowInitialize(BORDER,13,1,20,10,NORM,NORM,DOUBLEBOX);
WindowOpen(w1);
WindowOpen(w2);
WindowDisplay(w1,1,NOEFFECT);
WindowDisplay(w2,2,NOEFFECT);
VirtualWriteString(vw,"This is a string",1,1);/* Write string to
virtual window */
WindowAssignToVirtual(w1,vw,1,1); /* Assign viewport to virtual window */
WindowAssignToVirtual(w2,vw,1,1); /* Assign viewport to virtual window */
GET_KEY();
VirtualFree(vw,1,NOEFFECT); /* Destroy virtual window and hide
w1,w2 */
}
Page 161 The C Window Library Page 161
If there are no errors, VirtualFree() returns NO_ERROR.
If there are errors, VirtualFree() returns the following value:
BAD_V_WINDOW if the virtual window does not exist.
Page 162 The C Window Library Page 162
INTRODUCTION TO MENU SYSTEM
---------------------------
Menu systems are important entities in any program. The C Window Library has
functions that create popup, pull-down, and bar menus. The popup menus are
scrollable menus with a limit of 65,535 selections. The bar menus can have
any number of entries. As of this version, the bar menus are not scrollable,
although there will be an implementation of scrolling bar menus in a future
version. The pull-down menus are a combination of popup and bar menus.
You can change entries, hide entries, use hotkeys to invoke a menu entry,
and many more things.
Menu Manager
------------
The menu manager is the code in The C Window Library that handles moving the
highlight bar in the menu, calling the menu functions when they are selected,
keeps tracks of available entries, and other functions that keep track of the
menu when selections are made.
Necessary "include" files
-------------------------
To use the menu system in your program, you must include the "menu.h" file
supplied. This file automatically includes the "window.h" file, therefore
you do not have to include "window.h" when you use "menu.h".
Page 163 The C Window Library Page 163
POP-UP MENUS
------------
Description
-----------
A popup menu is a vertical menu with a list of entries that are selected by
placing a highlight bar on the entry and pressing return, or by invoking the
function by using a hotkey. Pop-up menus can be scrollable, in other words,
if there are more entries than can be displayed in the window, the menu will
scroll through the rest of the selections. You can have up to 65,535
selections in the popup menu.
Here is a partial list of the various options you can have with popup menus:
* Highlight bar wrapping - wrap highlight bar to first or last option
when there are no more selections.
* Static Menus - menu remains on the screen when entry is selected.
* Perpetual Menus - menu remain on the screen regardless of whether the
PopupSelectMenu() function (explained later) is called or not.
* Hidden (Unavailable) entries - You can make an entry in the popup menu
unavailable or available at any time.
* Color scheme of the menu - You can customize the color of the highlight
bar, the hotkey letters, hidden entries,
etc.
* Change entry names - You can safely change the names displayed in
the menu at any time.
* Use a mouse to select menu entries.
Windows and Virtual Windows
---------------------------
Pop-up menus use virtual windows to write menu selections, and use normal
windows to display the selections. This method of using virtual windows
enables the menu manager to scroll through the menu selections if the window
is not tall enough to display all of the selections.
Page 164 The C Window Library Page 164
CREATING POP-UP MENUS
---------------------
The POPUP_MENU_ENTRY structure
------------------------------
The two most important parts of the popup menu are the POPUP_MENU_ENTRY
structure and the POPUP_MENU_PTR structure. The POPUP_MENU_ENTRY structure
is the first step in creating a popup menu and is discussed here.
Each entry in the popup menu has its own POPUP_MENU_ENTRY structure
associated with it. The layout of this structure is as follows:
char *entry_name -- This is the string that is displayed in the
popup virtual window.
unsigned row -- Row in the virtual window to display entry_name.
char hotkey_letter -- This is a character in entry_name that is
highlighted from the rest of the characters in
entry_name. This letter will automatically
invoke the menu function associated with
entry_name.
unsigned ext_hotkey -- This is a secondary hotkey. The difference
between hotkey_letter and ext_hotkey is that
ext_hotkey can handle keys that are not ASCII keys
(the F keys, Alt and Ctrl key combinations, etc.).
int (*func)() -- Pointer to function that is invoked when option
is selected.
An array of POPUP_MENU_ENTRY's are needed to create all of the entries on the
popup menu. The order of the array elements determine the order of how they
are placed in the virtual window. A code sample to create an array of
POPUP_MENU_ENTRY's would be as follows:
#include "menu.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3", /* entry name */
1, /* row number */
'L', /* hotkey */
F3, /* secondary hotkey */
menu_func, /* function to call if
chosen */
Page 165 The C Window Library Page 165
/* now do rest of the popup entries */
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
/* Terminate with a CWL_NULL and 0 */
CWL_NULL,0};
The first include file, menu.h, is must be included in each source file that
calls menu functions.
As you can see, there is an array of POPUP_MENU_ENTRY's, namely menu_items.
Each entry consists of an entry name, row number, hotkey letter, secondary
hotkey, and a function to call when the entry is selected. The list of
POPUP_MENU_ENTRY's MUST be terminated by a CWL_NULL entry name, and a row
number of 0. If this rule is violated, the menu manager will not know where
the last entry is, and will cause chaos when the program is run.
If you are an advanced C programmer, you will no doubt find other ways in
creating the array of POPUP_MENU_ENTRY's. Other methods would be by dynamic
allocation, reading in the entries from a disk file, etc. The above example
illustrates the easiest way to create the POPUP_MENU_ENTRY's.
Defining Hotkeys
----------------
The hotkey_letter defined in the POPUP_MENU_ENTRY structure must match one of
the letters in its corresponding entry_name. For example, " Load F3",
has the hotkey_letter defined as 'L'. Since 'L' matches the first letter in
" Load F3", the first 'L' in " Load F3" is highlighted. If there is
no match, or if the hotkey_letter is 0, there is no hotkey associated with
this option. When the menu is displayed, either the 'l' or 'L' will be
accepted as a valid selection to the entry " Load F3". If there is a
POPUP_MENU_ENTRY with the same hotkey letter as another POPUP_MENU_ENTRY, the
POPUP_MENU_ENTRY closest to the first entry is chosen.
The ext_hotkey is used if the hotkey cannot be defined as a single character,
or if you want another hotkey definition. In the above example, the
" Load F3" entry_name has an ext_hotkey of F3 (defined in keycodes.h).
If the F3 key is pressed, the function menu_func() is automatically invoked.
If the ext_hotkey letter is 0, there is no ext_hotkey defined. If there is a
POPUP_MENU_ENTRY with the same ext_hotkey as another POPUP_MENU_ENTRY, the
POPUP_MENU_ENTRY closest to the first entry is chosen.
Page 166 The C Window Library Page 166
Assigning the function to perform
---------------------------------
The func() member is the function that is performed when its corresponding
entry_name is chosen.
This is the first step in completing the total popup menu. Once the array of
POPUP_MENU_ENTRY's is created the next step is to define the colors for each
element of the popup menu.
Coloring Popup Menus
--------------------
An array of unsigned integers is used to define the color scheme of the popup
menu. Each element of this array stands for a certain area of the popup
menu. Here is a list of array positions and what they stand for.
Position
Constant
--------
ENTRYCOLOR -- color of the text area of the viewport window.
BORDERCOLOR -- color of the border of the viewport window.
HOTKEYCOLOR -- color of the hotkey letter.
HIGHLIGHTCOLOR -- color of the highlight bar.
UNAVAILCOLOR -- color of the unavailable entries.
Position ENTRYCOLOR of the array defines the color of the text area of the
viewport window. This in turn defines the color of each entry_name of all
of the POPUP_MENU_ENTRY's.
Position BORDERCOLOR defines the color of the border of the viewport window.
As was stated above, the menu is written to a virtual window, and a viewport
is used to display the menu entries. If the viewport window does not have a
border, this attribute is ignored.
Position HOTKEYCOLOR defines the color to use for the hotkey letter. In the
above example, the 'L', 'P', 'N', etc. of each respective entry_name is
displayed using this color.
Position HIGHLIGHTCOLOR defines the color used for the highlight bar. This
bar is moved up and down when the user is making a selection.
Position UNAVAILCOLOR defines the color of the unavailable menu entries.
Whenever a menu entry is unavailable, the entry_name string displayed takes
on this color.
Colors can be created by using the CREATE_VIDEO_ATTRIBUTE(). A code sample
to create the colors is as follows:
Page 167 The C Window Library Page 167
#include "menu.h"
unsigned int menu_colors[5];
main()
{
{... code ...}
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* rest of the program */
}
As in creating the POPUP_MENU_ENTRY's, if you are an advanced programmer,
you will find other ways in assigning the colors.
PopupCreateMenu() function
--------------------------
Now that you have created the POPUP_MENU_ENTRY's, and defined the color
scheme, it is time to wrap all of these loose ends in one package. The next
step is to call the PopupCreateMenu() function. This function combines all
of the POPUP_MENU_ENTRY's, the colors you have defined, and other information
into one entity called a POPUP_MENU_PTR.
A POPUP_MENU_PTR is a pointer to a popup menu structure. Just like a
WPOINTER is a pointer to a window, a POPUP_MENU_PTR is used to reference the
popup menu.
A prototype of the call to PopupCreateMenu() is as follows:
POPUP_MENU_PTR PopupCreateMenu(POPUP_MENU_ENTRY *p, unsigned *color, int row,
int col, int height, unsigned options,
WPOINTER (*wfunc)(), VWPOINTER (*vfunc)())
To illustrate how to use this call, let's use the POPUP_MENU_ENTRY's and
colors created in the previous examples:
#include "menu.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3", /* entry name */
1, /* row number */
'L', /* hotkey */
F3, /* secondary hotkey */
menu_func, /* function to call if
chosen */
/* now do rest of the popup entries */
Page 168 The C Window Library Page 168
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
/* Terminate with a CWL_NULL and 0 */
CWL_NULL,0};
unsigned int menu_colors[5];
POPUP_MENU_PTR p;
main()
{
WindowInitializeSystem(); /* Initialize C Window Library */
/* define colors */
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a POPUP_MENU_PTR */
WindowSaveInitial(0); /* Save initial screen */
p = PopupCreateMenu(menu_items,menu_colors, 10,10,9,NO_POPUP_OPTIONS,
WNULLFN,VWNULLFN);
/* rest of the code */
}
In the example above there are two function calls that must be done before
calling PopupCreateMenu(). The first mandatory function is
WindowInitializeSystem(). The other function must be WindowSaveInitial()
The WindowInitializeSystem() function must be called to initialize global
variables used by the menu manager. The WindowSaveInitial() function is a
mandatory function because the PopupCreateMenu() function creates windows and
virtual windows and assumes that the base screen has been saved.
The example above declares the variable p to be a POPUP_MENU_PTR. This
POPUP_MENU_PTR is going to be used to reference the popup menu throughout the
program.
The first argument to PopupCreateMenu() is a pointer to the first
POPUP_MENU_ENTRY. In the above example, menu_items is a pointer to the
first POPUP_MENU_ENTRY.
Page 169 The C Window Library Page 169
The second argument is a pointer to the array of colors. In our example,
menu_colors is our array of colors.
The third and fourth arguments denote the row and column to place the upper
left hand corner of the popup menu window.
The fifth argument is the height of the popup menu window. If the height of
the window will not accommodate all of the menu items, the menu manager will
scroll the window so that the entries that are obscured come into view.
The sixth argument are various popup menu options that are assigned to the
popup menus which are defined below.
Popup Menu Options
------------------
By default the menu manager assumes the following things:
1) The highlight bar does not wrap if the user wants to move the bar past
the last entry, or before the first entry.
2) The menu will be hidden from the screen when a selection is made and
will reappear when control is returned to the menu manager.
3) A function is automatically invoked when the hotkey is pressed instead
of calling a user-defined function which will tell the menu manager
whether the menu entry is to be executed.
4) The popup menu window is hidden when the menu manager returns control
to the calling function.
5) The highlight bar will skip unavailable entries.
6) The menu manager does not recognize enhanced keys (F11, F12, etc.).
7) The mouse will not be used to move the highlight bar.
8) Scroll characters will not be displayed on the popup window. The
scroll characters allow the user to scroll through the options with a
mouse.
The last two options are only available if you have a Microsoft compatible
mouse, and the mouse is activated.
If the constant NO_POPUP_OPTIONS is used, the assumptions above are used. If
you want to override the above defaults, use the following options:
Page 170 The C Window Library Page 170
Option Name Definition
----------- ----------
POPUPWRAP Highlight bar wrapping.
POPUPSTATIC Do not hide menu when selection is made.
POPUPCONFIRM Confirmation when selection is made via hotkey.
POPUPDISPLAY Display menu even after exit.
POPUPOVERRIDE Accept Unavailable entries.
POPUPENHANCEDKEY Recognize enhanced keys.
POPUPMOUSE Use the mouse to select entries.
POPUPMOUSESCROLL Use the mouse to scroll through entries by placing
mouse on hotspots.
As was stated before, the last two options, POPUPMOUSE and POPUPSCROLLCHARS,
can only be used if you have a mouse installed, and the mouse is activated.
More information on these two options is given in the USING A MOUSE section.
By turning the above options "on" the following is assumed:
1) POPUPWRAP will wrap the highlight bar if the user wants to move the bar
past the last entry or before the first entry.
2) POPUPSTATIC will not hide the menu when a selection is made.
3) POPUPCONFIRM will call a user-defined function before invoking the
hotkey that was selected. This function will then return an integer
back to the menu manager informing whether the function selected should
be invoked, or the request should be rejected. There is more
information on this option in the SETTING OPTIONS IN POPUP MENUS
section below.
4) POPUPDISPLAY will not hide the popup window when the menu manager
returns control to the calling function.
5) POPUPOVERRIDE will make the menu manager accept unavailable entries.
6) POPUPENHANCEDKEY will inform the menu manager that enhanced keys will
be recognized.
7) POPUPMOUSE allows the use of a mouse to make selections.
8) POPUPMOUSESCROLL allows the user to scroll through the options using a
mouse.
You can also set multiple options by using a bitwise OR (|). For example:
p = PopupCreateMenu(arg1,arg2,arg3,arg4,arg5,
POPUPWRAP | POPUPSTATIC | POPUPCONFIRM,arg7,arg8)
will set options POPUPWRAP, POPUPSTATIC, and POPUPCONFIRM defined above.
Page 171 The C Window Library Page 171
The last two arguments to PopupCreateMenu() are defined in the next sections.
Default Popup Window and Creating Your own Windows
--------------------------------------------------
The sixth argument to the PopupCreateMenu() function is a pointer to a
function that will open a popup menu window. If this is a NULL function
pointer (WNULLFN), the menu manager will create a window. For most
applications, the window that the menu manager will create is adequate. The
menu manager uses these defaults when making the popup window:
- A bordered window with the border consisting of single lines (SINGLEBOX).
- The width of the window is determined by the longest entry_name in the
POPUP_MENU_ENTRY's.
If you want to create your own popup menu window, your function must return a
WPOINTER. Inside your function you must create and open a window using
WindowInitialize() and WindowOpen(). For most applications, you do not have
to display the window, instead the menu manager can do the displaying and
hiding of the windows.
Here is an example of creating your own custom window function:
#include "menu.h"
/* Other includes and menu stuff */
WPOINTER my_open();
POPUP_MENU_PTR p;
main()
{
/* Other code */
p = PopupCreateMenu(menu_items,menu_colors,10,10,9,my_open,WNULLFN);
/* More code */
}
WPOINTER my_open()
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,20,10,BLACKONWHITE,BLACKONWHITE,"");
WindowOpen(w);
return w; /* May be WIN_NULL_PTR, but must return to
PopupCreateMenu() */
}
The example above lets the menu manager know that the window creation
function is a user written function called my_open. The row, column and
height arguments (arguments 3, 4 and 5) of PopupCreateMenu() will be ignored
when using a custom window function. The row, column and height parameters
used to create the window in the call to WindowInitialize() in my_window()
will take precedence over the arguments 3, 4, and 5 used in PopupCreateMenu().
Page 172 The C Window Library Page 172
Default Virtual Window and
Creating Your own Virtual Windows
---------------------------------
The last argument to PopupCreateMenu() is a pointer to a function that will
return a VWPOINTER. This function creates the virtual window used to write
the menu entries. If this is a NULL function pointer (VWNULLFN), the menu
manager will create the virtual window. If you do specify a function, your
virtual window must have enough rows to hold all of the POPUP_MENU_ENTRY's,
and be wide enough to hold the length of the longest entry_name.
When the menu manager creates the virtual window, the following defaults are
assumed:
a) the virtual window has its own video attributes.
b) Must be large enough to hold all the POPUP_MENU_ENTRY's.
Your custom function should create a virtual window which follows both rules.
You must also make sure that the virtual window was created and opened
successfully. If the virtual window cannot be created because of a lack of
memory, you must return the NULL virtual window pointer instead. From there,
PopupCreateMenu() will do any cleaning up and will return with a null
POPUP_MENU_PTR.
My last advice when calling the PopupCreateMenu() function is that your best
bet is to let the menu manager create the windows and virtual windows. You
can always resize, change border types, etc. later on. Since virtual
window's are not visible anyway, it makes sense to let the menu manager
determine how the virtual window should be created. The last two arguments
to the PopupCreateMenu() function are for those programmers who need full
control of window, and virtual window management.
Accessing Popup Windows and Virtual Windows
-------------------------------------------
After calling the PopupCreateMenu() function, you can access the popup window
by using the POPUP_WINDOW() macro. In the above example, p is the
POPUP_MENU_PTR and the value of POPUP_WINDOW(p) is a pointer to the popup
menu's window. If you want to change borders move, slide, or anything you
can do with normal windows, you must access the popup window in this way.
For example, if you want to change the border of the popup window you would
do the following:
p = PopupCreateMenu(... /* other arguments */ )
WindowDrawBorder(POPUP_WINDOW(p),DOUBLEBOX); /* change border to a
double lined box */
The example calls WindowDrawBorder() to change the border of the popup
window.
Page 173 The C Window Library Page 173
If you want to write information to the virtual window created by the
PopupCreateMenu() function, you can access the virtual window by using the
POPUP_VIRTUAL_WINDOW() macro. By accessing the popup-menu's virtual window,
you can read and write to and from the virtual window. This is very useful
if you want to draw horizontal lines in your menu. An example would be as
follows:
char *h = "----------------------";
/* ...Some code... */
p = PopupCreateMenu(menu_items,menu_colors,10,10,9,WNULLFN,VWNULLFN);
VirtualWriteString(POPUP_VIRTUAL_WINDOW(p),h,8,1);
Warnings
--------
Do not call WindowFree(), WindowClose() or VirtualFree() on the window or the
virtual window of the popup menu. The menu manager will call these functions
when PopupMenuFree() is called. If you close the popup window, or the
virtual window on an active menu, the menu manager will assume that these
windows still exist. Doing so will almost guarantee your application will
bomb out.
Return Values for PopupCreateMenu()
-----------------------------------
If there are no errors, PopupCreateMenu() returns a valid POPUP_MENU_PTR
pointer. If there is an error when PopupCreateMenu() is called, a null
POPUP_MENU_PTR is returned. Here are the possible reasons why an error has
occurred:
1) There is not enough memory to allocate for the POPUP_MENU_PTR or its
internal data structures.
2) There is not enough memory to allocate for the popup window.
3) There is not enough memory to allocate for the virtual window.
4) The popup window's size was invalid.
Problems 1,2, and 3 all are caused by a lack of heap memory. Problem 4 stems
from having invalid parameters in the PopupCreateMenu(). The arguments that
are suspect are the third, fourth, and fifth arguments. To remedy this
problem, adjust these arguments such that the window can fit on the screen.
For all of the above conditions, you can get the actual error code by
checking the value of the global integer window_error_code. If
window_error_code is equal to NO_HEAP_MEM, then condition 1, 2, or 3 has
occurred. If it is equal to BAD_WINDOW_SIZE, then condition 4 has occurred.
Page 174 The C Window Library Page 174
If you have a custom window or virtual window opening function, it is your
responsibility to check the error conditions that may occur, and return
correct values or null pointers if you cannot rectify the error in your
custom routine.
Here is an example:
Example:
int status;
POPUP_MENU_PTR p;
p = PopupCreateMenu(...);
if (p == (POPUP_MENU_PTR)0) { /* check for null pointer */
if (window_error_code == NO_HEAP_MEM)
/* ... Condition 1,2, or 3 occurred */
else
/* Condition 4 occurred */
}
Page 175 The C Window Library Page 175
SELECTING FROM POPUP MENUS
--------------------------
We have now created the popup menu. Now how do we get the menu manager to
act on our popup window? The answer is the PopupSelectMenu() function.
PopupSelectMenu() function
--------------------------
The PopupSelectMenu() function displays the popup window, and allows the
user to move the highlight bar until he/she has placed the bar on the desired
option, or the user presses a hotkey to invoke one of the entries.
Before the call to the PopupSelectMenu(), nothing has been displayed. This
means that you can resize the popup window, change borders, write strings to
the popup menus virtual window, etc. while everything is hidden away from
view. The only time when the popup menu is displayed is when the call to
PopupSelectMenu() is made (or unless you have displayed the popup window
yourself using WindowDisplay()).
A prototype of the call to PopupSelectMenu() is as follows:
int PopupSelectMenu(POPUP_MENU_PTR p, int rank, unsigned start)
The first argument is the POPUP_MENU_PTR. The second argument is the rank of
the popup window. As with other windows, the rank determines how the window
will be situated on the screen with respect to the other windows. The last
argument is the number of the menu entry of where the highlight bar should be
situated. Usually this is 1, but this will give you the option to start on
any one of the menu entries. If the start value is out of bounds (say you
have specified start to be 5 while there are only 4 menu entries) the menu
manager will default to the first menu option.
Now let's put everything together:
#include "menu.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3", /* entry name */
1, /* row number */
'L', /* hotkey */
F3, /* secondary hotkey */
menu_func, /* function to call
if chosen */
/* now do rest of the popup entries */
Page 176 The C Window Library Page 176
" Pick Alt-F3",2, 'P',ALTF3,menu_func,
" New" ,3, 'N',0,menu_func,
" Save F2",4, 'S',F2,menu_func,
" Write to ",5, 'W',0,menu_func,
" Directory ",6, 'D',0,menu_func,
" Change Dir" ,7, 'C',0,menu_func,
" OS shell" ,8, 'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
/* Terminate with a CWL_NULL and 0 */
CWL_NULL,0};
unsigned int menu_colors[5];
POPUP_MENU_PTR p;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0); /* Remember to save the initial screen */
/* define colors */
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a POPUP_MENU_PTR */
p = PopupCreateMenu(menu_items,menu_colors, 1,1,6,POPUPSTATIC,WNULLFN,VWNULLFN);
PopupSelectMenu(p, /* POPUP_MENU_PTR */
1, /* rank of popup window */
1 /* menu entry to start on */
);
}
int menu_func(POPUP_MENU_PTR p, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX);
WindowOpen(w);
WindowClear(w);
WindowPrintf(w,"You have selected %s",POPUP_ENTRY_STRING(p,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return POPUP_EXIT;
else
return POPUP_CONTINUE;
}
Page 177 The C Window Library Page 177
The above example has a call to PopupSelectMenu(). The arguments passed are
p as the POPUP_MENU_PTR, a window rank of 1, and a starting position of 1.
The POPUP_ENTRY_STRING() macro in the menu_func() function returns the entry
string for the particualr menu entry. The first argument is the
POPUP_MENU_PTR and the second argument is the entry number.
Values passed to menu function
------------------------------
When a selection is made, the menu manager will call the function defined
for the selection, and pass two arguments to this function. The first
argument passed is the POPUP_MENU_PTR of the current popup menu and the
second argument is the number of the entry selected. Entry numbers are
numbered from 1 to the highest entry in the menu. For example, if the " Load
F3" entry is selected, the menu manager will pass the POPUP_MENU_PTR p, and a
1 to func(). If " Pick ALT-F3" is chosen, the menu manager passes a 2 as the
second argument to func() etc.
Values returned to menu manager
-------------------------------
The user function must return an integer back to the menu manager. If the
value returned to the menu manager is POPUP_EXIT, the menu manager will exit
from the current menu and will return control back to the function that
called it. If the return value is POPUP_CONTINUE, the menu continues to
process selections.
The menu_func() function defined above creates a window, displays the entry
you have chosen, and returns a value back to the menu manager. If the value
is POPUP_EXIT, the menu manager returns control back to the function that
called it. In this case, main() called PopupSelectMenu(). A return value of
POPUP_CONTINUE will cause the menu manager to let the user make another
selection.
The menu_func() function is a simple implementation. However your function
can do much more sophisticated things, including opening other popup menus.
If another popup menu is called while in another popup menu, the new popup
menu gets its own menu manager and will not interfere with the original menu
manager. This is good if a menu function will call another menu function.
Page 178 The C Window Library Page 178
Return Values for PopupSelectMenu()
-----------------------------------
If no errors occurred when PopupSelectMenu() is called the menu manager
returns NO_ERROR when the menu is closed. There are three possibilities for
errors when calling PopupSelectMenu(). Here are the three possible errors:
1) The popup menus window does not exist.
2) The popup menus window is not opened.
3) The virtual window does not exist.
The first error occurred because the PopupCreateMenu() function or your
custom window function could not initialize the popup menu window, you
inadvertently called WindowFree() on the popup menu's window, or you are
overwriting data with a stray pointer.
Error 2 can occur if the you inadvertently called WindowClose() on the popup
menu's window, or you are overwriting data with a stray pointer.
Error 3 can occur if PopupCreateMenu() or your custom virtual window
function could not create the virtual window, or a stray pointer is
overwriting data.
For all of the above conditions, you can get the actual error code by
checking the value of the global integer window_error_code or by checking
the return value of PopupSelectMenu(). Here is a list of return values and
their corresponding reasons:
Return Value Condition
------------ ---------
BAD_WINDOW 1
WINDOW_NOT_OPEN 2
BAD_V_WINDOW 3
Page 179 The C Window Library Page 179
SETTING OPTIONS IN POPUP MENUS
------------------------------
In addition to setting options using the PopupCreateMenu() function, you can
turn on and off options at any time using the PopupSetOptions() function.
The PopupSetOptions() function
------------------------------
The PopupSetOptions() function turns either one or more of the above
options on or off. The prototype to the call is as follows:
int PopupSetOptions(POPUP_MENU_PTR p, int option, int switch)
The first argument is the POPUP_MENU_PTR. The second argument are the
options that you wish to change. The constants that describe the options are
exactly the same as the ones described in PopupCreateMenu(). The third
argument is whether you want to switch the options on or off.
Here are some sample calls to PopupSetOptions():
a) PopupSetOptions(p,POPUPWRAP,1)
b) PopupSetOptions(p,POPUPSTATIC,1)
c) PopupSetOptions(p,POPUPCONFIRM,1)
d) PopupSetOptions(p,POPUPSTATIC,0)
e) PopupSetOptions(p,POPUPDISPLAY,1)
f) PopupSetOptions(p,POPUPOVERRIDE,1)
g) PopupSetOptions(p,POPUPENHANCEDKEY,1)
The third argument is 1 for "on", 0 for "off".
Example a) sets the highlight bar so that it will wrap.
Example b) informs the menu manager that the menu will not be hidden when a
selection is made.
Example c) will tell the menu manager to call a user defined function that
will inform the menu manager whether to invoke the selection in the menu.
Example d) Informs the menu manager to hide the menu window when a menu
function is invoked.
Example e) Informs the menu manager not to hide the menu when control is
returned to the function that called PopupSelectMenu().
Example f) Informs the menu manager to process unavailable entries. This is
useful if you want to set up your own error routine if the user selects an
unavailable entry.
Example g) imforms the menu manager to distinguish between normal keys and
enhanced keys.
Page 180 The C Window Library Page 180
Setting Multiple Options
------------------------
You can also set multiple options with a single call by using a bitwise OR
(|). For example:
PopupSetOptions(p,POPUPWRAP | POPUPSTATIC | POPUPCONFIRM,1)
will set options POPUPWRAP, POPUPSTATIC, and POPUPCONFIRM defined above.
Setting the PopupSetConfirmFunction()
-------------------------------------
When using the POPUPCONFIRM option, you must also use the
PopupSetConfirmFunction() function to point the menu to the confirmation
function that will be called when a hotkey is pressed. Here is a prototype
of the PopupSetConfirmFunction():
PopupSetConfirmFunction(POPUP_MENU_PTR p, int (*func)())
where p is the desired popup menu to assign the confirmation function to,
and func is a pointer to a function that will return a value back to the menu
manager that will inform it to either invoke the option, or ignore the
option.
When the confirmation function is called, the menu manager passes three
arguments to func. The prototype for your user defined function should be as
follows:
int my_confirm_func(POPUP_MENU_PTR p, unsigned key, unsigned sel)
where p is the POPUP_MENU_PTR that is currently being processed, key is the
hotkey that was pressed, and sel is the selection where the highlight bar is
now positioned. The highlight bar is always positioned on the hotkey
selection even if it may not be invoked. This user defined function must
return a value back to the menu manager. The valid values that can be
returned are POPUP_CONTINUE and POPUP_DO_CHOICE. If POPUP_CONTINUE is
returned, the menu selection is not invoked, if POPUP_DO_CHOICE is selected,
the menu entry is invoked. Here is an example:
#include "menu.h"
int my_confirm_func();
POPUP_MENU_PTR p;
/* ... */
main()
{
PopupSetOptions(p,POPUPCONFIRM,1);
PopupSetConfirmFunction(p,my_confirm_func);
/* ... */
}
Page 181 The C Window Library Page 181
my_confirm_func(POPUP_MENU_PTR p, unsigned k, unsigned sel)
{
/* ... */
if (k == 'C' || k == 'c' || k == ALTF)
return POPUP_CONTINUE;
else
return POPUP_DO_CHOICE;
}
The above function invokes the menu selection if the hotkey that was pressed
is not a 'C', 'c', or ALT-F.
The confirmation function can do anything, including setting options in the
popup menu, displaying other windows etc.
Return Values for PopupSetOptions() function
--------------------------------------------
You can use the PopupSetOptions() function at any time, including before
calling the PopupSelectMenu() function. If the option is not a valid option,
the function returns NO_ERROR, but does not change anything. If the switch
is not 0 or 1, a 1 is assumed.
If there is an error, the error conditions and reasons are the same as the
PopupSelectMenu() function defined above.
Page 182 The C Window Library Page 182
MAKING MENU ENTRIES AVAILABLE AND UNAVAILABLE
---------------------------------------------
There may be cases when a menu entry should be made unavailable. The entry
shows up in the menu, but it is a different color than the other entries, and
the highlight bar will just skip over this unavailable entry.
PopupMakeEntryAvailable() and
PopupMakeEntryUnavailable() functions
-------------------------------------
With The C Window Library, you can make entries available and unavailable at
any time. The PopupMakeEntryAvailable() and the PopupMakeEntryUnavailable()
functions perform these tasks.
A prototype of the call to both of these functions is as follows:
int PopupMakeEntryAvailable(POPUP_MENU_PTR p, unsigned entry)
int PopupMakeEntryUnavailable(POPUP_MENU_PTR p, unsigned entry)
The first argument is the POPUP_MENU_PTR. The second argument is the number
of the entry that you wish to change. Entry numbers range from 1 to the
highest entry in the menu.
POPUPOVERRIDE option
--------------------
If the POPUPOVERRIDE option is set (see above), the menu manager will still
process unavailable entries. You must turn off POPUPOVERRIDE by using the
PopupSetOptions() function if you do not want to process unavailable entries.
Return Values for PopupMakeEntryAvaialble() and
PopupMakeEntryUnavailable() functions
-----------------------------------------------
If there is no error, both of these functions return NO_ERROR.
If there is an error, the following possibilities can occur:
1) The error can be one of the errors defined above for the PopupSelectMenu()
2) The menu entry is invalid.
Refer to the PopupSelectMenu() return values and reasons for failure defined
above for error condition 1). If the error is 2), check to see if the entry
number supplied is valid. The entry number cannot be < 1 or greater than the
number of selections in the popup menu.
Page 183 The C Window Library Page 183
If error 2) has occurred, the PopupMakeEntryAvailable() and the
PopupMakeEntryUnavailable() return MENU_ENTRY_INVALID.
Page 184 The C Window Library Page 184
CHANGING THE MENU ENTRY STRINGS
-------------------------------
There may be times when you want to change a POPUP_MENU_ENTRY entry_name
string. For instance, you may have a menu entry with the following
entry_name:
"Default File Name ABC.DAT"
If the user selects this choice, the file name should change to another file
name the user wants. From there the menu should reflect the new choice the
user has made. Let's say the user has changed the default file name to
DEF.DAT. The menu then should say:
"Default File Name DEF.DAT"
PopupChangeEntryString() function
---------------------------------
How do you change the entry string? One way is to fool around with the
POPUP_MENU_PTR's structure members, and change the string yourself. This is
not recommended for the novice to average C programmer, since it is not a good
idea to change the structure members directly without a full understanding of
the structure.
A safer way is to call the PopupChangeEntryString() function. A prototype of
this function is as follows:
PopupChangeEntryString(POPUP_MENU_PTR p, unsigned entry, char *newstring)
The first argument is the POPUP_MENU_PTR. The second argument is the number
of the entry that you wish to change. Entry numbers range from 1 to the
highest entry in the menu. The third argument is a pointer to the new
character string. The newstring cannot be longer than the current
POPUP_MENU_ENTRY entry_name string.
Return Values for PopupChangeEntryString() function
---------------------------------------------------
If there is no error, NO_ERROR is returned.
If there is an error, the error conditions and reasons are the same as the
PopupMakeEntryAvailable() function defined above.
Page 185 The C Window Library Page 185
REDEFINING MENU KEYS
--------------------
Setting Global Key Definitions and
the popup_key_definition Array
----------------------------------
You can redefine the keys used to control moving the highlight bar, accepting
the menu choice, and exiting from the menu. Here is a list of the default key
mapping:
Function Key Constant
-------- --- ------
Move highlight bar up Up Arrow POPUP_UPKEY
Move highlight bar down Down Arrow POPUP_DOWNKEY
Accept Menu Choice Enter POPUP_ACCEPTKEY
Escape Pop-up menu Escape POPUP_QUITKEY
Move To First Menu Item Home POPUP_HOMEKEY
Move to Last Menu Item End POPUP_ENDKEY
Scroll entries up by one
page PgUp POPUP_PAGEUPKEY
Scroll entries down by one
page PgDn POPUP_PAGEDOWNKEY
*Move To Next Popup Menu Not Assigned POPUP_RIGHTKEY
*Move to Previous Popup Menu Not Assigned POPUP_LEFTKEY
*Escape Pulldown Menu Not Assigned POPUP_PULLDOWN_QUITKEY
The global array popup_key_definition contains the values of the default
popup menu key definitions. The names under the Constant heading are the
offsets in the popup_key_definition array of where the key value for the
function is defined. For instance, the value for the "Move highlight bar up"
function is located at popup_key_definition[POPUP_UPKEY]. You can change the
values in popup_key_definition at any time, but make sure that a definition
for "Escape Pop-up menu" always exists, and that there are no duplicate
definitions (i.e. the "Move highlight bar up" key definition is the same as
the "Move highlight bar down" key definition). When defining new key values,
you should use the values defined in the keycodes.h header file for non-ascii
keys.
* The POPUP_RIGHTKEY, POPUP_LEFTKEY, and the POPUP_PULLDOWN_QUITKEY
definitions only apply to popup menus that are incorporated in a pulldown
menu. See the section on pulldown menus for more information.
Setting Local Key Definitions
-----------------------------
Another way of redefining menu keys is to load your own array of key
definitions with your desired values, and then calling the PopupAssignKeys()
function. With this method, each menu can have different key definitions.
Page 186 The C Window Library Page 186
PopupAssignKeys() function
--------------------------
Here is a prototype of the PopupAssignKeys() function:
int PopupAssignKeys(POPUP_MENU_PTR p, unsigned *keys)
where p is the POPUP_MENU_PTR, and keys is an array of key definitions. Here
is a small code example:
#include "menu.h"
unsigned mykeys[NUMPOPUPKEYS] = {CTRLU,CTRLD,RETURN,ESC,HOME,END,0,0,0,0};
POPUP_MENU_PTR p;
/* Other stuff...*/
main()
{
/* Assume p is initialized */
PopupAssignKeys(p,mykeys); /* Assigns my key definitions to popup menu p */
}
The constant NUMPOPUPKEYS should be used to make sure that your array of key
definitions is large enough to hold all the definitions. The above example
uses the constants defined in keycodes.h to assign to the array mykeys. Each
position in the mykeys array uses the default key mapping explained above.
In other words, mykeys[POPUP_UPKEY] is CTRLU, etc.
Return Values for PopupAssignKeys() function
--------------------------------------------
If there is no error, then NO_ERROR is returned.
If there is an error, the error conditions and reasons are the same as the
PopupSelectMenu() function defined above.
Page 187 The C Window Library Page 187
PROCESSING UNDEFINED KEYS
-------------------------
If you are an advanced programmer and/or have experience in using other
window/menu libraries, you may be wondering "how do I define a function that
supplies context-sensitive help for each POPUP_MENU_ENTRY? There is no
structure member in POPUP_MENU_ENTRY that supplies this". With The C Window
Library, any key that is not recognized by the menu manager (i.e. the key
struck does not invoke a menu option, move the highlight bar up or down, or
ends processing of the menu) can be processed by calling a user written
function. The WindowGet...() family of functions allowed us to define a
function that will be called if a key that has no current definition is
pressed. For popup menus, we can do the same thing.
The popup_undef_key function pointer
------------------------------------
The global function pointer, popup_undef_key, can point to a user written
function that will be called when the menu manager encounters a key that is
not defined. The declaration for popup_undef_key is as follows:
unsigned int (*popup_undef_key)(POPUP_MENU_PTR p, unsigned int sel,
unsigned int *choice)
The user written function takes three arguments. The first argument is a
pointer to the popup menu that the menu manager is currently processing. The
second argument is an integer that contains the value of the key that was
pressed. The third argument is a pointer to an integer that will contain the
number of the menu choice to execute. Initially, choice points to an integer
that contains the current menu choice that the menu highlight bar is situated.
For instance, if the highlight bar is on the first menu choice when an
undefined key is pressed, *choice will be equal to 1. If popup_undef_key is
equal to a Null Function pointer (NULLFN), no user defined function is called.
By default, popup_undef_key is assigned to NULLFN.
Values returned to menu manager
-------------------------------
If popup_undef_key is assigned to a function, the function must return an
integer back to the menu manager. This integer value will tell the menu
manager how to proceed. Here is a list of the valid return values that the
user written function can return:
Page 188 The C Window Library Page 188
Return Action to
Value Take
------ ---------
POPUP_CONTINUE No Action. Continue processing the popup menu.
POPUP_MOVE_UP Move the highlight bar up.
POPUP_MOVE_DOWN Move the highlight bar down.
POPUP_DO_CHOICE Accept and invoke menu entry assigned to *choice.
POPUP_MOVE_CONTINUE Move the highlight bar to menu entry assigned to
*choice and continue processing menu.
POPUP_ESCAPE Escape the popup menu.
POPUP_MOVE_HOME Move highlight to first available menu entry.
POPUP_MOVE_END Move highlight to last available menu entry.
POPUP_MOVE_PAGEUP Scroll the entries in the popup window up by one
"page" (a page is the current height of the popup
window).
POPUP_MOVE_PAGEDOWN Scroll the entries in the popup window down by one
"page" (a page is the current height of the popup
window).
*POPUP_MOVE_LEFT Move to next popup menu.
*POPUP_MOVE_RIGHT Move to previous popup menu.
*POPUP_PULLDOWN_QUIT Escape pulldown menu
A return value of POPUP_CONTINUE is a "do nothing" command to the menu
manager.
If POPUP_DO_CHOICE is returned to the menu manager, the integer assigned to
the parameter *choice is used as the menu entry to invoke. The highlight
bar will automatically be moved to the menu choice specified, and the menu
function will be called. If POPUP_MOVE_CONTINUE is returned to the menu
manager, the highlight bar will be moved to the entry specified by the
value of *choice, but no function is called.
Return values of POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE only work when the
menu entry specified by *choice is an available entry or the POPUPVERRIDE
option is on , otherwise the menu manager just continues processing the
popup menu.
* The POPUP_MOVE_RIGHT, POPUP_MOVE_LEFT, and POPUP_PULLDOWN_QUIT only apply
to popup menus that are incorporated in a pulldown menu system. See the
section on pulldown menus for more information.
Here is an example of using a user defined function for the undefined keys:
#include "menu.h"
/* Other includes */
int user_func();
Page 189 The C Window Library Page 189
main()
{
popup_undef_key = user_func;
/* Other code */
}
unsigned int user_func(POPUP_MENU_PTR p, unsigned sel, unsigned *choice)
{
switch(sel)
{
case F1:
help(*choice); /* call help function */
return POPUP_CONTINUE; /* return "do nothing" command to menu manager */
case F2:
*choice = 6; /* let menu manager know to do choice 6 on the menu */
return POPUP_DO_CHOICE; /* Also let menu manager know we are
returning the "do the function assigned to
*choice" command */
default:
return POPUP_CONTINUE;
/* let menu manager know not to do anything */
}
}
int help(int choice)
{ /* help function */
switch (choice)
{
case 1:
/* do context-sensitive help for entry 1 */
break;
case 2:
/* do context-sensitive help for entry 2 */
break;
/* do more entries */
/* ... */
}
}
In the above example, if the user hits F1, a help function is called. If you
wanted to know how to incorporate a help function in the popup menus, here is
the way to do it.
If the user hits F2, the integer pointed to by choice is assigned a 6, and
user_func() returns POPUP_DO_CHOICE to the menu manager. This tells the
menu manager to invoke the function assigned to menu entry 6.
Page 190 The C Window Library Page 190
PRE-INPUT FUNCTION
------------------
With The C Window Library, you can define a function that will be performed
just before the menu manager waits for the user to enter a keystroke. This
function can perform just about anything.
Setting the global_popup_prefunc function pointer
-------------------------------------------------
The global_popup_prefunc function pointer points to this user written
function. Here is the prototype:
int (*global_popup_prefunc)(POPUP_MENU_PTR p, unsigned *sel)
The arguments that will be passed to your function are the following:
a) The POPUP_MENU_PTR of the popup menu that called your function, and
b) A pointer to the number of the selection that the highlight bar is
currently on.
The selection number ranges from 1 to the highest entry number of the menu.
The pre-input function MUST return a value back to the menu manager. The
return values that can be returned are the same as the popup_undef_key
function described above. If you are using a version of The C Window Library
prior to version 1.5, you must declare your pre-input function as returning
an int, and you must return a value back to the menu manager. Versions prior
to 1.5 declared the pre-input function as void.
The POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE return values will move the
highlight bar to the entry number that is assigned to the *sel argument when
the pre-input function has returned.
By default, global_popup_prefunc points to a NULLFN, and therefore will not be
performed. However, you can implement pre-input functions depending on the
current selection. For instance, you can write a function that displays
extra information for each entry like so:
#include "menu.h"
char *mess[] = {
" This option saves and loads files",
" This brings you in edit mode",
" This compiles and/or links the current program",
/* ... More stuff */
};
Page 191 The C Window Library Page 191
WPOINTER message_window;
int disp_info();
main()
{
/* ... */
global_popup_prefunc = disp_info;
/* ... */
}
int disp_info(POPUP_MENU_PTR p, unsigned *sel)
{
/* Assume message_window already created and opened */
WindowClear(message_window,CREATE_VIDEO_ATTRIBUTE(black,white));
WindowWriteString(message_window,mess[*sel-1],1,1);
return POPUP_CONTINUE;
}
For simplicity, the menu definitions are left out of the preceding code
sample. The disp_info displays the appropriate description in the window
message_window. POPUP_CONTINUE is returned to the menu manager. This
informs the menu manager to continue looking for a keystroke.
Page 192 The C Window Library Page 192
DISPOSING OF POPUP MENUS
------------------------
PopupMenuFree()
---------------
If the popup menu is no longer needed, the PopupMenuFree() function will
dispose of the popup menu and return any memory allocated to the popup menu,
window, and virtual window memory back to the heap. The call to the function
is very simple:
PopupMenuFree(POPUP_MENU_PTR p)
where p is the POPUP_MENU_PTR to dispose of. Since this function destroys the
POPUP_MENU_PTR p, p must not be used for any popup menu functions, unless p
is pointing to a valid POPUP_MENU_PTR.
Return Values for PopupMenuFree()
---------------------------------
The return values and the reasons for failure are the same as
PopupSelectMenu().
Page 193 The C Window Library Page 193
BAR MENUS
---------
Description
-----------
A bar menu is a horizontal menu with a list of entries that are selected by
placing a highlight bar on the option and pressing return, or by invoking the
function by using a hotkey. Bar menus can span several lines. In other
words, menu entries do not have to fit on a single line.
Here is a partial list of the various options you can have with bar menus:
* Highlight bar wrapping - wrap highlight bar to first or last option
when there are no more selections.
* Static Menus - menu remains on the screen when entry is
selected.
* Perpetual Menus - menu remain on the screen regardless of
whether the BarSelectMenu() function
(explained later) is called or not.
* Hidden (Unavailable) entries - You can make an entry in the bar menu
unavailable or available at any time.
* Color scheme of the menu - You can customize the color of the highlight
bar, the hotkey letters, hidden entries,
etc.
* Change entry names - You can safely change the names displayed in
the menu at any time.
* Use a mouse to select menu entries.
Windows and Virtual Windows
---------------------------
Unlike popup menus, bar menus do not use virtual windows. Only normal text
windows are used.
Page 194 The C Window Library Page 194
CREATING BAR MENUS
------------------
The BAR_MENU_ENTRY structure
----------------------------
The two most important parts of the bar menu are the BAR_MENU_ENTRY structure
and the BAR_MENU_PTR structure. The BAR_MENU_ENTRY structure is the first
step in creating a bar menu and is discussed here.
Each entry in the bar menu has its own BAR_MENU_ENTRY structure associated
with it. The layout of this structure is as follows:
char *entry_name -- This is the string that is displayed in the
bar window.
unsigned row -- Row in the window to display entry_name.
char hotkey_letter -- This is a character in entry_name that is
highlighted from the rest of the characters in
entry_name. This letter will automatically
invoke the menu function associated with
entry_name.
unsigned ext_hotkey -- This is a secondary hotkey. The difference
between hotkey_letter and ext_hotkey is that
ext_hotkey can handle keys that are not ASCII keys
(the F keys, Alt and Ctrl key combinations, etc.).
int (*func)() -- Pointer to function that is invoked when option
is selected.
An array of BAR_MENU_ENTRY's are needed to create all of the entries on the
bar menu. The order of the array elements determine the order of how they
are placed in the window. A code sample to create an array of
BAR_MENU_ENTRY's would be as follows:
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File", /* option name */
1, /* row in window to display option name */
4, /* col. in window to display option */
'F', /* hotkey letter */
ALTF, /* secondary hotkey */
rt2, /* function to do if chosen */ ,
Page 195 The C Window Library Page 195
/* Now define the rest of the BAR_MENU_ENTRY's */
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options",1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
/* Now terminate with a CWL_NULL option_name */
CWL_NULL};
The first include file, menu.h, is must be included in each source file that
calls menu functions.
As you can see, there is an array of BAR_MENU_ENTRY's, namely bar_items.
Each entry consists of an entry name, row number, column number, hotkey
letter, secondary hotkey, and a function to call when the entry is selected.
The list of BAR_MENU_ENTRY's MUST be terminated by a CWL_NULL entry name.
If you are an advanced C programmer, you will no doubt find other ways in
creating the array of BAR_MENU_ENTRY's. Other methods would be by dynamic
allocation, reading in the entries from a disk file, etc. The above example
illustrates the easiest way to create the BAR_MENU_ENTRY's.
If you are an advanced C programmer, you will no doubt find other ways in
creating the array of BAR_MENU_ENTRY's. Other methods would be by dynamic
allocation, reading in the entries from a disk file, etc. The above example
illustrates the easiest way to create the BAR_MENU_ENTRY's.
Defining Hotkeys
----------------
The hotkey_letter defined in the BAR_MENU_ENTRY structure must match one of
the letters in its corresponding entry_name. For example, "File", has the
hotkey_letter defined as 'F'. Since 'F' matches the first letter in "File",
the first 'F' in "File" is highlighted. If there is no match, or if the
hotkey_letter is 0, there is no hotkey associated with this entry. When the
menu is displayed, either the 'f' or 'F' will be accepted as a valid selection
to the entry "File". If there is a BAR_MENU_ENTRY with the same hotkey
letter as another BAR_MENU_ENTRY, the BAR_MENU_ENTRY closest to the first
entry is chosen.
The ext_hotkey is used if the hotkey cannot be defined as a single character,
or if you want another hotkey definition. In the above example, the "File"
entry_name has an ext_hotkey of ALTF3 (defined in keycodes.h). If the ALT-F3
key is pressed, the function rt2() is automatically invoked. If the
ext_hotkey letter is 0, there is no ext_hotkey defined. If there is a
BAR_MENU_ENTRY with the same ext_hotkey as another BAR_MENU_ENTRY, the
BAR_MENU_ENTRY closest to the first entry is chosen.
Page 196 The C Window Library Page 196
Assigning the function to perform
---------------------------------
The func() member is the function that is performed when its corresponding
entry_name is chosen.
This is the first step in completing the total bar menu. Once the array of
BAR_MENU_ENTRY's is created the next step is to define the colors for each
element of the bar menu.
Coloring Bar Menus
------------------
An array of unsigned integers is used to define the color scheme of the bar
menu. Each element of this array stands for a certain area of the bar
menu. Here is a list of array positions and what they stand for.
Position
Constant
--------
ENTRYCOLOR -- color of the text area of the window.
BORDERCOLOR -- color of the border of the window.
HOTKEYCOLOR -- color of the hotkey letter.
HIGHLIGHTCOLOR -- color of the highlight bar.
UNAVAILCOLOR -- color of the unavailable entries.
Position ENTRYCOLOR of the array defines the color of the text area of the
viewport window. This in turn defines the color of each entry_name of all
of the BAR_MENU_ENTRY's.
Position BORDERCOLOR defines the color of the border of the window. If
the window does not have a border, this attribute is ignored.
Position HOTKEYCOLOR defines the color to use for the hotkey letter. In the
above example, the 'L', 'P', 'N', etc. of each respective entry_name is
displayed using this color.
Position HIGHLIGHTCOLOR defines the color used for the highlight bar. This
bar is moved up and down when the user is making a selection.
Position UNAVAILCOLOR defines the color of the unavailable menu entries.
Whenever a menu entry is unavailable, the entry_name string displayed takes
on this color.
Colors can be created by using the CREATE_VIDEO_ATTRIBUTE() macro. A code
sample to create the colors is as follows:
Page 197 The C Window Library Page 197
#include "menu.h"
unsigned int menu_colors[5];
main()
{
{... code ...}
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* rest of the program */
}
As in creating the BAR_MENU_ENTRY's, if you are an advanced programmer,
you will find other ways in assigning the colors.
BarCreateMenu() function
------------------------
Now that you have created the BAR_MENU_ENTRY's, and defined the color
scheme, it is time to wrap all of these loose ends in one package. The next
step is to call the BarCreateMenu() function. This function combines all
of the BAR_MENU_ENTRY's, the colors you have defined, and other information
into one entity called a BAR_MENU_PTR.
A BAR_MENU_PTR is a bar menu structure. Just like a WPOINTER is a
pointer to a window, a BAR_MENU_PTR is used to reference the bar menu.
A prototype of the call to BarCreateMenu() is as follows:
BAR_MENU_PTR BarCreateMenu(BAR_MENU_ENTRY *b, unsigned *c, int row,
int col, unsigned options,
WPOINTER (*wfunc)())
To illustrate how to use this call, let's use the BAR_MENU_ENTRY's and
colors created in the previous examples:
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,NULLFN,
"Edit",1,10,'E',0,edit,
"Run",1,17,'R',0,NULLFN,
"Compile",1,23,'C',0,NULLFN,
"Project",1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug",1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
Page 198 The C Window Library Page 198
unsigned int menu_colors[5];
BAR_MENU_PTR b;
main()
{
WindowInitializeSystem(); /* Initialize C Window Library */
/* define colors */
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a BAR_MENU_PTR */
WindowSaveInitial(0); /* Save initial screen */
b = BarCreateMenu(menu_items,menu_colors,1,1,NO_BAR_OPTIONS,WNULLFN);
/* rest of the code */
}
In the example above there are two function calls that must be done before
calling BarCreateMenu(). The first mandatory function is
WindowInitializeSystem(). The other function must be WindowSaveInitial()
The WindowInitializeSystem() function must be called to initialize global
variables used by the menu manager. The WindowSaveInitial() function is a
mandatory function because the BarCreateMenu() function creates windows and
assumes that the base screen has been saved.
The example above declares the variable b to be a BAR_MENU_PTR. This
BAR_MENU_PTR is going to be used to reference the bar menu throughout the
program.
The first argument is a pointer to the first BAR_MENU_ENTRY. In the above
example, menu_items is a pointer to the first BAR_MENU_ENTRY.
The second argument is a pointer to the array of colors. In our example,
menu_colors is our array of colors.
The third and fourth arguments denote the row and column to place the upper
left hand corner of the bar menu window.
The fifth argument are various bar menu options that are assigned to the
bar menus which are defined below.
Page 199 The C Window Library Page 199
Bar Menu Options
----------------
By default the menu manager assumes the following things:
1) The highlight bar does not wrap if the user wants to move the bar past
the last entry, or before the first entry.
2) The menu will be hidden from the screen when a selection is made and
will reappear when control is returned to the menu manager.
3) A function is automatically invoked when the hotkey is pressed instead
of calling a user-defined function which will tell the menu manager
whether the menu entry is to be executed.
4) The bar menu window is hidden when the menu manager returns control
to the calling function.
5) The highlight bar will skip unavailable entries.
6) The menu manager does not recognize enhanced keys (F11, F12, etc.).
7) The mouse will not be used to move the highlight bar.
8) Scroll characters will not be displayed on the bar window. The
scroll characters allow the user to scroll through the options with a
mouse.
The last two options are only available if you have a Microsoft compatible
mouse, and the mouse is activated.
If the constant NO_BAR_OPTIONS is used, the assumptions above are used. If
you want to override the above defaults, use the following options:
Option Name Definition
----------- ----------
BARWRAP Highlight bar wrapping.
BARSTATIC Do not hide menu when selection is made.
BARCONFIRM Confirmation when selection is made via hotkey.
BARDISPLAY Display menu even after exit.
BAROVERRIDE Accept Unavailable entries.
BARENHANCEDKEY Recognize enhanced keys.
BARMOUSE Use the mouse to select entries.
As was stated before, the last option, BARMOUSE can only be used if you have
a mouse installed, and the mouse is activated. More information on these two
options is given in the USING THE MOUSE section.
By turning the above options "on" the following is assumed:
Page 200 The C Window Library Page 200
1) BARWRAP will wrap the highlight bar if the user wants to move the bar
past the last entry or before the first entry.
2) BARSTATIC will not hide the menu when a selection is made.
3) BARCONFIRM will call a user-defined function before invoking the
hotkey that was selected. This function will then return an integer
back to the menu manager informing whether the function selected should
be invoked, or the request should be rejected. There is more
information on this option in the SETTING OPTIONS IN BAR MENUS
section below.
4) BARDISPLAY will not hide the bar window when the menu manager
returns control to the calling function.
5) BAROVERRIDE will make the menu manager accept unavailable entries.
6) BARENHANCEDKEY will inform the menu manager that enhanced keys will
be recognized.
7) BARMOUSE allows the use of a mouse to make selections.
You can also set multiple options by using a bitwise OR (|). For example:
b = BarCreateMenu(arg1,arg2,arg3,arg4,BARWRAP | BARSTATIC | BARCONFIRM,
arg5)
will set options BARWRAP, BARSTATIC, and BARCONFIRM defined above.
The last argument to BarCreateMenu() is defined in the next sections.
Default Bar Menu Window and Creating Your own Windows
-----------------------------------------------------
The sixth argument to the BarCreateMenu() function is a pointer to a
function that will open a bar menu window. If this is a NULL function
pointer (WNULLFN), the menu manager will create a window. For most
applications, the window that the menu manager will create is adequate. The
menu manager uses these defaults when making the bar window:
- A bordered window with the border consisting of single lines (SINGLEBOX).
- The width of the window is determined by the longest row of entry names.
If you want to create your own bar menu window, your function must return a
WPOINTER. Inside your function you must create and open a window using
WindowInitialize() and WindowOpen(). For most applications, you do not have
to display the window, instead the menu manager can do the displaying and
hiding of the windows.
Page 201 The C Window Library Page 201
Here is an example of creating your own custom window function:
#include "menu.h"
/* Other includes and menu stuff */
WPOINTER my_open();
BAR_MENU_PTR b;
main()
{
/* Other code */
b = BarCreateMenu(menu_items,menu_colors,1,1,NO_BAR_OPTIONS,my_open);
/* More code */
}
WPOINTER my_open()
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE,BLACKONWHITE,"");
WindowOpen(w);
return w; /* May be null pointer,
but must return to BarCreateMenu() */
}
The example above lets the menu manager know that the window creation
function is a user written function called my_open. The row, column and
height arguments (arguments 3 and 4) of BarCreateMenu() will be ignored
when using a custom window function. The row and column height parameters
used to create the window in the call to WindowInitialize() in my_window()
will take precedence over the arguments 3 and 4 used in BarCreateMenu().
It is the programmer's responsibility to make sure that the window that is
created is wide and tall enough to hold all of the menu entries. If not, the
results will be unpredictable.
Accessing bar menu windows
--------------------------
After calling the BarCreateMenu() function, you can access the bar window
by using the BAR_WINDOW() macro. In the above example, b is the
BAR_MENU_PTR and the value of BAR_WINDOW(b) is a pointer to the bar
menu's window. If you want to change borders move, slide, or anything you
can do with normal windows, you must access the bar window in this way.
For example, if you want to change the border of the bar window you would
do the following:
Page 202 The C Window Library Page 202
b = BarCreateMenu(... /* other arguments */ )
WindowDrawBorder(BAR_WINDOW(b),DOUBLEBOX); /* change border to a
double lined box */
The example calls WindowDrawBorder() to change the border of the bar
window.
Warnings
--------
Do not call WindowFree(), WindowClose() on the window of the bar menu. The
menu manager will call these functions when BarMenuFree() is called. If you
close the bar window on an active menu, the menu manager will assume that the
bar window still exists. Doing so will almost guarantee your application
will bomb out.
Return Values for BarCreateMenu()
---------------------------------
If there are no errors, BarCreateMenu() returns a valid BAR_MENU_PTR
pointer. If there is an error when BarCreateMenu() is called, a null
BAR_MENU_PTR is returned. Here are the possible reasons why an error has
occurred:
1) There is not enough memory to allocate for the BAR_MENU_PTR or its
internal data structures.
2) There is not enough memory to allocate for the bar window.
3) The bar window's size was invalid.
Problems 1 and 2 all are caused by a lack of heap memory. Problem 3 stems
from having invalid parameters in the BarCreateMenu(). The arguments that
are suspect are the third and fourth. To remedy this problem, adjust these
arguments such that the window can fit on the screen.
For all of the above conditions, you can get the actual error code by
checking the value of the global integer window_error_code. If
window_error_code is equal to NO_HEAP_MEM, then condition 1 or 2 has
occurred. If it is equal to BAD_WINDOW_SIZE, then condition 3 has occurred.
If you have a custom window opening function, it is your responsibility to
check the error conditions that may occur, and return a correct value or a
null pointer if you cannot rectify the error in your custom routine.
Page 203 The C Window Library Page 203
Here is an example:
Example:
int status;
BAR_MENU_PTR b;
b = BarCreateMenu(...);
if (b == (BAR_MENU_PTR)0) { /* check for null BAR_MENU_PTR pointer */
if (window_error_code == NO_HEAP_MEM)
/* ... Condition 1 or 2 occurred */
else
/* Condition 3 occurred */
}
Page 204 The C Window Library Page 204
SELECTING FROM BAR MENUS
------------------------
We have now created the bar menu. Now how do we get the menu manager to
act on our bar window? The answer is the BarSelectMenu() function.
BarSelectMenu() function
------------------------
The BarSelectMenu() function displays the bar window, and allows the
user to move the highlight bar until he/she has placed the bar on the desired
entry, or the user presses a hotkey to invoke one of the entries.
Before the call to the BarSelectMenu(), nothing has been displayed. This
means that you can resize the bar window, change borders etc. while
everything is hidden away from view. The only time when the bar menu is
displayed is when the call to BarSelectMenu() is made (or unless you have
displayed the bar window yourself using WindowDisplay()).
A prototype of the call to BarSelectMenu() is as follows:
int BarSelectMenu(BAR_MENU_PTR b, int rank, unsigned start)
The first argument is the BAR_MENU_PTR. The second argument is the rank of
the bar window. As with other windows, the rank determines how the window
will be situated on the screen with respect to the other windows. The last
argument is the number of the menu entry of where the highlight bar should be
situated. Usually this is 1, but this will give you the option to start on
any one of the menu entries. If the start value is out of bounds (say you
have specified start to be 5 while there are only 4 menu entries) the menu
manager will default to the first menu entry.
Now let's put everything together:
#include "menu.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,menu_func,
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options", 1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
CWL_NULL};
Page 205 The C Window Library Page 205
unsigned int menu_colors[5];
BAR_MENU_PTR b;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0); /* Remember to save the initial screen */
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a BAR_MENU_PTR */
b = BarCreateMenu(bar_items,menu_colors, 1,1,BARSTATIC | BARWRAP,WNULLFN);
BarSelectMenu(b,1,1);
}
int menu_func(BAR_MENU_PTR b, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX);
WindowOpen(w);
WindowPrintf(w,"You have selected %s",BAR_ENTRY_STRING(b,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return BAR_EXIT;
else return BAR_CONTINUE;
}
The above example has a call to BarSelectMenu(). The arguments passed are
b as the BAR_MENU_PTR, a window rank of 1, and a starting position of 1. The
BAR_ENTRY_STRING() macro that is called in menu_func() returns the entry
string of a desired entry in a BAR_MENU_PTR. The first argument is the
BAR_MENU_PTR, and the second argument is the entry number of the entry
desired.
Values passed to menu function
------------------------------
When a selection is made, the menu manager will call the function defined
for the selection, and pass two arguments to this function. The first
argument passed is the BAR_MENU_PTR of the current bar menu and the
second argument is the number of the item selected. Item numbers are
numbered from 1 to the highest entry in the menu. For example, if the "File"
entry is selected, the menu manager will pass the BAR_MENU_PTR b, and a
1 to func(). If "Edit" is chosen, the menu manager passes a 2 as the
second argument to func() etc.
Page 206 The C Window Library Page 206
Values returned to menu manager
-------------------------------
The user function must return an integer back to the menu manager. If the
value returned to the menu manager is BAR_EXIT, the menu manager will exit
from the current menu and will return control back to the function that
called it. If the return value is BAR_CONTINUE, the menu continues to
process selections.
The menu_func() function defined above creates a window, displays the entry
you have chosen, and returns a value back to the menu manager. If the value
is BAR_EXIT, the menu manager returns control back to the function that
called it. In this case, main() called BarSelectMenu(). A return value of
BAR_CONTINUE will cause the menu manager to let the user make another
selection.
The menu_func() function is a simple implementation. However your function
can do much more sophisticated things, including opening other bar menus. If
another bar menu is called while in another bar menu, the new bar menu gets
its own menu manager and will not interfere with the original menu manager.
This is good if a menu function will call another menu function.
Return Values for BarSelectMenu()
---------------------------------
If no errors occurred when BarSelectMenu() is called the menu manager
returns NO_ERROR when the menu is closed. There are three possibilities for
errors when calling BarSelectMenu(). Here are the three possible errors:
1) The bar menu's window does not exist.
2) The bar menu's window is not opened.
The first error occurred because the BarCreateMenu() function or your
custom window function could not initialize the bar menu window, you
inadvertently called WindowFree() on the bar menu's window, or you are
overwriting data with a stray pointer.
Error 2 can occur if the you inadvertently called WindowClose() on the bar
menu's window, or you are overwriting data with a stray pointer.
For all of the above conditions, you can get the actual error code by
checking the value of the global integer window_error_code or by checking
the return value of BarSelectMenu(). Here is a list of return values and
their corresponding reasons:
Return Value Condition
------------ ---------
BAD_WINDOW 1
WINDOW_NOT_OPEN 2
Page 207 The C Window Library Page 207
SETTING OPTIONS IN BAR MENUS
----------------------------
In addition to setting options using the BarCreateMenu() function, you can
turn on and off options at any time using the BarSetOptions() function.
The BarSetOptions() function
----------------------------
The BarSetOptions() function turns either one or more of the above
options on or off. The prototype to the call is as follows:
int BarSetOptions(BAR_MENU_PTR b, int option, int switch)
The first argument is the BAR_MENU_PTR. The second argument are the options
that you wish to change. The constants that describe the options are exactly
the same as the ones described in BarCreateMenu(). The third argument is
whether you want to switch the options on or off.
Here are some sample calls to BarSetOptions():
a) BarSetOptions(b,BARWRAP,1)
b) BarSetOptions(b,BARSTATIC,1)
c) BarSetOptions(b,BARCONFIRM,1)
d) BarSetOptions(b,BARSTATIC,0)
e) BarSetOptions(b,BARDISPLAY,1)
f) BarSetOptions(b,BAROVERRIDE,1)
g) BarSetOptions(b,BARENHANCEDKEY,1)
The third argument is 1 for "on", 0 for "off".
Example a) sets the highlight bar so that it will wrap.
Example b) informs the menu manager that the menu will not be hidden when a
selection is made.
Example c) will tell the menu manager to call a user defined function that
will inform the menu manager whether to invoke the selection in the menu.
Example d) Informs the menu manager to hide the menu window when a menu
function is invoked.
Example e) Informs the menu manager not to hide the menu when control is
returned to the function that called BarSelectMenu().
Example f) Informs the menu manager to process unavailable entries. This is
useful if you want to set up your own error routine if the user selects an
unavailable entry.
Example g) imforms the menu manager to distinguish between normal keys and
enhanced keys.
Page 208 The C Window Library Page 208
Setting Multiple Options
------------------------
You can also set multiple options with a single call by using a bitwise OR
(|). For example:
BarSetOptions(b,BARWRAP | BARSTATIC | BARCONFIRM,1)
will set options BARWRAP, BARSTATIC, and BARCONFIRM defined above.
Setting the BarSetConfirmFunction()
-----------------------------------
When using the BARCONFIRM option, you must also use the
BarSetConfirmFunction() function to point the menu to the confirmation
function that will be called when a hotkey is pressed. Here is a prototype
of the BarSetConfirmFunction():
BarSetConfirmFunction(BAR_MENU_PTR b, int (*func)())
where b is the desired bar menu to assign the confirmation function to,
and func is a pointer to a function that will return a value back to the menu
manager that will inform it to either invoke the option, or ignore the
option.
When the confirmation function is called, the menu manager passes three
arguments to func. The prototype for your user defined function should be as
follows:
int my_confirm_func(BAR_MENU_PTR b, unsigned key, unsigned sel)
where b is the BAR_MENU_PTR that is currently being processed, key is
the hotkey that was pressed, and sel is the selection where the highlight bar
is now positioned. The highlight bar is always positioned on the hotkey
selection even if it may not be invoked. This user defined function must
return a value back to the menu manager. The valid values that can be
returned are BAR_CONTINUE and BAR_DO_CHOICE. If BAR_CONTINUE is
returned, the menu selection is not invoked, if BAR_DO_CHOICE is selected,
the menu entry is invoked. Here is an example:
#include "menu.h"
int my_confirm_func();
BAR_MENU_PTR b;
/* ... */
main()
{
BarSetOptions(b,BARCONFIRM,1);
BarSetConfirmFunction(b,my_confirm_func);
/* ... */
}
Page 209 The C Window Library Page 209
my_confirm_func(BAR_MENU_PTR b, unsigned k, unsigned sel)
{
/* ... */
if (k == 'C' || k == 'c' || k == ALTF)
return BAR_CONTINUE;
else
return BAR_DO_CHOICE;
}
The above function invokes the menu selection if the hotkey that was pressed
is not a 'C', 'c', or ALT-F.
The confirmation function can do anything, including setting options in the
bar menu, displaying other windows etc.
Return Values for BarSetOptions() function
------------------------------------------
You can use the BarSetOptions() function at any time, including before
calling the BarSelectMenu() function. If the option is not a valid option,
the function returns NO_ERROR, but does not change anything. If the switch
is not 0 or 1, a 1 is assumed.
If there is an error, the error conditions and reasons are the same as the
BarSelectMenu() function defined above.
Page 210 The C Window Library Page 210
MAKING ENTRIES AVAILABLE AND UNAVAILABLE
----------------------------------------
There may be cases when a menu entry should be made unavailable. The entry
shows up in the menu, but it is a different color than the other entries, and
the highlight bar will just skip over this unavailable entry.
BarMakeEntryAvailable() and
BarMakeEntryUnavailable() functions
-----------------------------------
With The C Window Library, you can make entries available and unavailable at
any time. The BarMakeEntryAvailable() and the BarMakeEntryUnavailable()
functions perform these tasks.
A prototype of the call to both of these functions is as follows:
int BarMakeEntryAvailable(BAR_MENU_PTR b, unsigned entry)
int BarMakeEntryUnavailable(BAR_MENU_PTR b, unsigned entry)
The first argument is the BAR_MENU_PTR. The second argument is the number
of the entry that you wish to change. Entry numbers range from 1 to the
highest entry in the menu.
BAROVERRIDE option
------------------
If the BAROVERRIDE option is set (see above), the menu manager will still
process unavailable entries. You must turn off BAROVERRIDE by using the
BarSetOptions() function if you do not want to process unavailable entries.
Return Values for BarMakeEntryAvaialble() and
BarMakeEntryUnavailable() functions
---------------------------------------------
If there is no error, both of these functions return NO_ERROR.
If there is an error, the following possibilities can occur:
1) The error can be one of the errors defined above for the BarSelectMenu()
2) The menu entry is invalid.
Refer to the BarSelectMenu() return values and reasons for failure defined
above for error condition 1). If the error is 2), check to see if the entry
number supplied is valid. The entry number cannot be < 1 or greater than the
number of selections in the bar menu.
If error 2) has occurred, the BarMakeEntryAvailable() and the
BarMakeEntryUnavailable() return MENU_ENTRY_INVALID.
Page 211 The C Window Library Page 211
CHANGING THE MENU OPTIONS STRING
--------------------------------
There may be times when you want to change a BAR_MENU_ENTRY entry_name
string. For instance, you may have a menu entry with the following
entry_name:
"Default File Name ABC.DAT"
If the user selects this choice, the file name should change to another file
name the user wants. From there the menu should reflect the new choice the
user has made. Let's say the user has changed the default file name to
DEF.DAT. The menu then should say:
"Default File Name DEF.DAT"
BarChangeEntryString() function
-------------------------------
How do you change the entry string? One way is to fool around with the
BAR_MENU_PTR's structure members, and change the string yourself. This is
not recommended for the novice to average C programmer, since it is not a good
idea to change the structure members directly without a full understanding of
the structure.
A safer way is to call the BarChangeEntryString() function. A prototype of
this function is as follows:
BarChangeEntryString(BAR_MENU_PTR b, unsigned entry, char *newstring)
The first argument is the BAR_MENU_PTR. The second argument is the number
of the entry that you wish to change. Entry numbers range from 1 to the
highest entry in the menu. The third argument is a pointer to the new
character string. Remember that the width of the bar menu's window is equal
to the width of the longest line of entry_name entries, therefore
newstring cannot exceed the boundaries of the bar menu window (unless you
will called WindowResizeWidth() or WindowResizeHeight() to resize the window).
Return Values for BarChangeEntryString() function
-------------------------------------------------
If there is no error, then NO_ERROR is returned.
If there is an error, the error conditions and reasons are the same as the
BarMakeEntryAvailable() function defined above.
Page 212 The C Window Library Page 212
REDEFINING THE MENU KEYS
------------------------
Setting Global Key Definitions and
the bar_key_definition Array
----------------------------------
You can redefine the keys used to control moving the highlight bar, accepting
the menu choice, and exiting from the menu. Here is a list of the default key
mapping:
Function Key Constant
-------- --- ------
Move highlight bar right Up Arrow BAR_RIGHTKEY
Move highlight bar left Down Arrow BAR_LEFTKEY
Accept Menu Choice Enter BAR_ACCEPTKEY
Escape Bar menu Escape BAR_QUITKEY
Move To First Menu Item Home BAR_HOMEKEY
Move to Last Menu Item End BAR_ENDKEY
The global array bar_key_definition contains the values of the default
bar menu key definitions. The names under the Constant heading are the
offsets in the bar_key_definition array of where the key value for the
function is defined. For instance, the value for the "Move highlight bar up"
function is located at bar_key_definition[BAR_RIGHTKEY]. You can change the
values in bar_key_definition at any time, but make sure that a definition
for "Escape Bar menu" always exists, and that there are no duplicate
definitions (i.e. the "Move highlight bar up" key definition is the same as
the "Move highlight bar down" key definition). When defining new key values,
you should use the values defined in the keycodes.h header file for non-ascii
keys.
Setting Local Key Definitions
-----------------------------
Another way of redefining menu keys is to load your own array of key
definitions with your desired values, and then calling the BarAssignKeys()
function. With this method, each menu can have different key definitions.
BarAssignKeys() function
------------------------
Here is a prototype of the BarAssignKeys() function:
int BarAssignKeys(BAR_MENU_PTR b, unsigned *keys)
where b is the BAR_MENU_PTR, and keys is an array of key definitions. Here
is a small code example:
Page 213 The C Window Library Page 213
#include "menu.h"
unsigned mykeys[8] = {CTRLR,CTRLL,RETURN,ESC,HOME,END};
BAR_MENU_PTR b;
/* Other stuff...*/
main()
{
/* Assume b is initialized */
BarAssignKeys(b,mykeys); /* Assigns my key definitions to bar menu b */
}
The above example uses the constants defined in keycodes.h to assign to the
array mykeys. Each position in the mykeys array uses the default key mapping
explained above. In other words, mykeys[BAR_RIGHTKEY] is CTRLR, etc.
Return Values for BarAssignKeys() function
------------------------------------------
If there is no error, then NO_ERROR is returned.
If there is an error, the error conditions and reasons are the same as the
BarSelectMenu() function defined above.
Page 214 The C Window Library Page 214
PROCESSING UNDEFINED KEYS
-------------------------
If you are an advanced programmer and/or have experience in using other
window/menu libraries, you may be wondering "how do I define a function that
supplies context-sensitive help for each BAR_MENU_ENTRY? There is no
structure member in BAR_MENU_ENTRY that supplies this". With The C Window
Library, any key that is not recognized by the menu manager (i.e. the key
struck does not invoke a menu option, move the highlight bar up or down, or
ends processing of the menu) can be processed by calling a user written
function. The WindowGet...() family of functions allowed us to define a
function that will be called if a key that has no current definition is
pressed. For bar menus, we can do the same thing.
The bar_undef_key function pointer
----------------------------------
The global function pointer, bar_undef_key, can point to a user written
function that will be called when the menu manager encounters a key that is
not defined. The declaration for bar_undef_key is as follows:
unsigned int (*bar_undef_key)(BAR_MENU_PTR b, unsigned int sel,
unsigned int *choice)
The user written function takes three arguments. The first argument is a
pointer to the bar menu that the menu manager is currently processing. The
second argument is an integer that contains the value of the key that was
pressed. The third argument is a pointer to an integer that will contain the
number of the menu choice to execute. Initially, choice points to an integer
that contains the current menu choice that the menu highlight bar is situated.
For instance, if the highlight bar is on the first menu choice when an
undefined key is pressed, *choice will be equal to 1. If bar_undef_key is
equal to a Null Function pointer (NULLFN), no user defined function is called.
By default, bar_undef_key is assigned to NULLFN.
Values returned to menu manager
-------------------------------
If bar_undef_key is assigned to a function, the function must return an
integer back to the menu manager. This integer value will tell the menu
manager how to proceed. Here is a list of the valid return values that the
user written function can return:
Page 215 The C Window Library Page 215
Return Action to
Value Take
------ ---------
BAR_CONTINUE No Action. Continue processing the bar menu.
BAR_DO_CHOICE Accept and invoke menu entry assigned to *choice.
BAR_MOVE_CONTINUE Move the highlight bar to menu entry assigned to
*choice and continue processing menu.
BAR_ESCAPE Escape the bar menu.
BAR_MOVE_LEFT Move to next bar menu.
BAR_MOVE_RIGHT Move to previous bar menu.
BAR_MOVE_HOME Move highlight to first available menu entry.
BAR_MOVE_END Move highlight to last available menu entry.
A return value of BAR_CONTINUE is a "do nothing" command to the menu
manager.
If BAR_DO_CHOICE is returned to the menu manager, the integer assigned to
the parameter *choice is used as the menu entry to invoke. The highlight
bar will automatically be moved to the menu choice specified, and the menu
function will be called. If BAR_MOVE_CONTINUE is returned to the menu
manager, the highlight bar will be moved to the entry specified by the
value of *choice, but no function is called.
Return values of BAR_DO_CHOICE and BAR_MOVE_CONTINUE only work when the
menu entry specified by *choice is an available entry or the BAROVERRIDE
option is on , otherwise the menu manager just continues processing the
bar menu.
Here is an example of using a user defined function for the undefined keys:
#include "menu.h"
/* Other includes */
int user_func();
main()
{
bar_undef_key = user_func;
/* Other code */
}
Page 216 The C Window Library Page 216
unsigned int user_func(BAR_MENU_PTR b, unsigned sel, unsigned *choice)
{
switch(sel)
{
case F1:
help(*choice); /* call help function */
return BAR_CONTINUE; /* return "do nothing" command to menu manager */
case F2:
*choice = 6; /* let menu manager know to do choice 6 on the menu */
return BAR_DO_CHOICE; /* Also let menu manager know we are
returning the "do the function assigned to
*choice" command */
default:
return BAR_CONTINUE;
/* let menu manager know not to do anything */
}
}
int help(int choice)
{ /* help function */
switch (choice)
{
case 1:
/* do context-sensitive help for entry 1 */
break;
case 2:
/* do context-sensitive help for entry 2 */
break;
/* do more entries */
/* ... */
}
}
In the above example, if the user hits F1, a help function is called. If you
wanted to know how to incorporate a help function in the bar menus, here is
the way to do it.
If the user hits F2, the integer pointed to by choice is assigned a 6, and
user_func() returns BAR_DO_CHOICE to the menu manager. This tells the
menu manager to invoke the function assigned to menu entry 6.
Page 217 The C Window Library Page 217
PRE-INPUT FUNCTION
------------------
With The C Window Library, you can define a function that will be performed
just before the menu manager waits for the user to enter a keystroke. This
function can perform just about anything.
Setting the global_bar_prefunc function pointer
-------------------------------------------------
The global_bar_prefunc function pointer points to this user written
function. Here is the prototype:
int (*global_bar_prefunc)(BAR_MENU_PTR p, unsigned *sel)
The arguments that will be passed to your function are the following:
a) The BAR_MENU_PTR of the bar menu that called your function, and
b) A pointer to the number of the selection that the highlight bar is
currently on.
The selection number ranges from 1 to the highest entry number of the menu.
The pre-input function MUST return a value back to the menu manager. The
return values that can be returned are the same as the bar_undef_key
function described above. If you are using a version of The C Window Library
prior to version 1.5, you must declare your pre-input function as returning
an int, and you must return a value back to the menu manager. Versions prior
to 1.5 declared the pre-input function as void.
The BAR_DO_CHOICE and BAR_MOVE_CONTINUE return values will move the highlight
bar to the entry number that is assigned to the *sel argument when the
pre-input function has returned.
By default, global_bar_prefunc points to a NULLFN, and therefore will not be
performed. However, you can implement pre-input functions depending on the
current selection. For instance, you can write a function that displays
extra information for each entry like so:
#include "menu.h"
char *mess[] = {
" This option saves and loads files",
" This brings you in edit mode",
" This compiles and/or links the current program",
/* ... More stuff */
};
Page 218 The C Window Library Page 218
WPOINTER message_window;
int disp_info();
main()
{
/* ... */
global_bar_prefunc = disp_info;
/* ... */
}
int disp_info(BAR_MENU_PTR p, unsigned *sel)
{
/* Assume message_window already created and opened */
WindowClear(message_window,CREATE_VIDEO_ATTRIBUTE(black,white));
WindowWriteString(message_window,mess[*sel-1],1,1);
return BAR_CONTINUE;
}
For simplicity, the menu definitions are left out of the preceding code
sample. The disp_info displays the appropriate description in the window
message_window. BAR_CONTINUE is returned to the menu manager. This
informs the menu manager to continue looking for a keystroke.
Page 219 The C Window Library Page 219
DISPOSING OF BAR MENUS
----------------------
BarMenuFree() function
----------------------
If the bar menu is no longer needed, the BarMenuFree() function will
dispose of the bar menu and return any memory allocated to the bar menu,
window, and window memory back to the heap. The call to the function
is very simple:
BarMenuFree(BAR_MENU_PTR b)
where b is the BAR_MENU_PTR to dispose of. Since this function destroys the
BAR_MENU_PTR b, b must not be used for any bar menu functions, unless b
is pointing to a valid BAR_MENU_PTR.
Return Values for BarMenuFree()
-------------------------------
The return values and the reasons for failure are the same as
BarSelectMenu(). Please refer to this section.
Page 220 The C Window Library Page 220
PULLDOWN MENUS
--------------
Description
-----------
A pulldown menu is a combination of popup menus and a bar menu. The bar menu
portion of the pulldown menu acts the same way as a normal bar menu. However
when a choice is made from the bar menu, a popup menu appears with more
options to choose. An example of a pulldown menu is the integrated environ-
ments of the Quick C and Turbo C compilers.
Most of what was discussed previously will apply to pulldown menus. Make
sure that you have read the sections on popup menus and bar menus before
preceding.
Bar Menu and Popup Menu levels
------------------------------
With pulldown menus there are two levels; the bar menu level and the popup
menu level. When in the bar menu level, no popup menu's are displayed, and
the move right and move left keys move the highlight bar to the next or
previous selection in the bar menu. When in the popup menu level, the move
right and move left keys not only move the highlight in the bar menu, but
will also display the popup menu associated with the bar menu option.
Page 221 The C Window Library Page 221
CREATING PULLDOWN MENUS
-----------------------
There are 4 steps that must be done when creating pulldown menus. They are as
follows:
Step 1) Create the bar menu portion by calling BarCreateMenu().
Step 2) Create each popup menu to be displayed underneath the bar by
calling the PopupCreateMenu() function.
Step 3) Group all popup menus created in step 2 into an array of popup
menu's.
Step 4) Call PulldownCreateMenu().
For Step 1) the bar menu is created the same way as described in the Bar
Menu section of this manual. The only difference is that if there is a
popup window that will be displayed under the bar menu option, the function
pointer for that BAR_MENU_ENTRY must be a NULLFN (null integer function
pointer). Otherwise, if there is no popup menu defined for that bar menu
option, the BAR_MENU_ENTRY's function pointer must point to a valid function.
For instance, here is a sample array of BAR_MENU_ENTRY's used to create the
Turbo C integrated environments bar menu:
BAR_MENU_ENTRY bar_items[] = {
"File", 1,4, 'F',0,NULLFN,
"Edit", 1,10,'E',0,menu_func,
"Run", 1,17,'R',0,NULLFN,
"Compile", 1,23,'C',0,NULLFN,
"Project", 1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug", 1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
In the above example, All of the entries have a NULLFN function pointer except
for the "Edit" entry. The entries with NULLFN function pointers will have
popup windows displayed under them when they are selected. The "Edit" option
will not have a popup menu displayed under it. Instead, the menu_func()
function is performed instead when "Edit" is chosen.
Step 2) is as described in the Popup windows section.
Step 3) can be done as follows:
Page 222 The C Window Library Page 222
POPUP_MENU_PTR popup_list[8];
main() {
/* ... */
popup_list[0] = PopupCreateMenu(/*..argument list..*/);
popup_list[1] = (POPUP_MENU_PTR)0; /* No popup, so value must be NULL */
popup_list[2] = PopupCreateMenu(/*..argument list..*/);
popup_list[3] = PopupCreateMenu(/*..argument list..*/);
popup_list[4] = PopupCreateMenu(/*..argument list..*/);
popup_list[5] = PopupCreateMenu(/*..argument list..*/);
popup_list[6] = PopupCreateMenu(/*..argument list..*/);
popup_list[7] = PopupCreateMenu(/*..argument list..*/);
The above example shows each element of popup_list is assigned to the return
value of PopupCreateMenu(), except for popup_list[1]. Note that
popup_list[1] is a null POPUP_MENU_PTR. Here is the reason. Let's say that
there is an option on the bar menu that DOES NOT have a popup menu associated
with it. In other words, it is just a single function option, and no
sub-functions are possible. The entry in the array of POPUP_MENU_PTR's that
will correspond to the position of where there is no popup menu should be
NULL. The above example shows that the second POPUP_MENU_PTR is non-existent
(matches with the BAR_MENU_ENTRY called "Edit", which is the second bar
entry).
Once the bar menu and popup menus are created, you can set options by
calling the BarSetOptions() or the PopupSetOptions() function, assign menu
keys using the BarAssignKeys() or PopupAssignKeys() functions, etc. just as
described earlier in this manual. Remember that a pulldown menu just
incorporates all of your menus into one manageable entity.
The PulldownCreateMenu() function
---------------------------------
The next step (Step 4) is done by calling the PulldownCreateMenu() function.
This function integrates the bar menu and the array of popup menus in a
single unit. A pointer to this unit is returned. This pointer is declared
as a PULLDOWN_MENU_PTR. The prototype form the PulldownCreateMenu() function
is as follows:
PULLDOWN_MENU_PTR PulldownCreateMenu(POPUP_MENU_PTR popups[],
BAR_MENU_PTR bar,
int adjust)
The first argument is a pointer to an array of POPUP_MENU_PTR's. In the
above example, the second argument is the BAR_MENU_PTR. Here is an example of
how to use the PulldownCreateMenu() function:
Page 223 The C Window Library Page 223
#include "menu.h"
BAR_MENU_ENTRY bar_items[] = {
"File", 1,4, 'F',0,NULLFN,
"Edit", 1,10,'E',0,menu_func,
"Run", 1,17,'R',0,NULLFN,
"Compile", 1,23,'C',0,NULLFN,
"Project", 1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug", 1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
POPOP_MENU_ENTRY p1[] = {
/* Popup entries */,
CWL_NULL,0 };
POPUP_MENU_ENTRY p2[] = POPUP_NULL_ENTRY; /* This constant defines an empty
POPUP_MENU_ENTRY */
POPUP_MENU_ENTRY p3[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p4[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p5[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p6[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p7[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_ENTRY p7[] = {
/* More popup entries */
CWL_NULL, 0 };
POPUP_MENU_PTR popup_list[8];
BAR_MENU_PTR bar;
PULLDOWN_MENU_PTR pull;
Page 224 The C Window Library Page 224
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
bar = BarCreateMenu(bar_items, { other arguments } );
popup_list[0] = PopupCreateMenu(p1, { other arguments } );
popup_list[1] = p2;
popup_list[2] = PopupCreateMenu(p3, { other arguments } );
popup_list[3] = PopupCreateMenu(p4, { other arguments } );
popup_list[4] = PopupCreateMenu(p5, { other arguments } );
popup_list[5] = PopupCreateMenu(p6, { other arguments } );
popup_list[6] = PopupCreateMenu(p7, { other arguments } );
popup_list[7] = PopupCreateMenu(p8, { other arguments } );
pull = PulldownCreateMenu(popup_list,bar,1);
{...}
}
In the above example, bar is a BAR_MENU_PTR, p1, p2, p3, p4, etc. are all
lists of POPUP_MENU_ENTRY's. The array of POPUP_MENU_PTR's is called
popup_list, and the PULLDOWN_MENU_PTR is called pull. Please note the use of
the POPUP_NULL_ENTRY constant. Use this constant when initializing a
POPUP_MENU_ENTRY list to no items.
The bar menu is initialized by calling BarCreateMenu() using bar_items as the
list of BAR_MENU_ENTRY's. The PopupCreateMenu() is called for each member of
the popup_list array. Note that the popup_list[1] is assigned a null
POPUP_MENU_PTR. This indicates that there is no popup menu for the second
bar item ("Edit"). Even though it is not shown, you should check to see if
BarCreateMenu() and all of the PopupCreateMenu() function calls returned
without error.
The call to PulldownCreateMenu() is done with the first argument being the
the pointer to the array of POPUP_MENU_PTR's, namely popup_list. The second
argument is the BAR_MENU_PTR bar, and the last argument is discussed in the
next section.
Automatic Adjustment of Popup Windows
-------------------------------------
The last argument to PulldownCreateMenu() will inform the menu manager to
adjust all the popup menu window positions, so that they fit neatly under the
bar menu. If the adjust argument in PulldownCreateMenu() is a 1, the
previous (row,col) positions of each popup menu window is ignored
(Arguments 3 and 4 of PopupCreateMenu()), and the menu manager decides where
the popup window should be placed on the screen. Otherwise, if adjust is 0,
the previous values of the (row,col) position of the popup menu is used.
Here is how the menu manager decides where the popup window should be placed:
Page 225 The C Window Library Page 225
a) The first attempt tries to place the left hand corner of the popup window
under the first character of the option name in the bar menu. If the
column on the screen where we have placed the popup window, plus the
popup windows width does not exceed the width of the bar, then we have
found a "good" position for the popup window, if not then do step b).
b) We place the upper right hand corner of the popup window underneath the
last column of the bar menu's window. If the upper left-hand corner of
the popup window can be placed in a screen column greater than or equal
to 1, then we have found the "good" position. If the upper left-hand
corner cannot be placed in column 1 then do step c).
c) Place the upper left hand corner of the popup window at the first column
of the bar menu window. If this does not work then do step d).
d) place the popup window in column 1 of the screen.
Here are a few examples of the above scenarios:
1)
-------------------------------------------------------------
| File Edit Compile Options Project |
| |
-------------------------------------------------------------
| |
|Condition a)|
| worked! |
| |
|------------|
2a)
-------------------------------------------------------------
| File Edit Compile Options Project |
| |
----------------------------------------------------------------------
| |
| Too wide! option a) failed! |
| |
| Try option b) |
| |
|--------------------------------|
2b)
-------------------------------------------------------------
| File Edit Compile Options Project |
| |
-------------------------- ------------------------- -------- ----------
| |
| option b) worked! |
| |
|--------------------------------|
Page 226 The C Window Library Page 226
In the first example, 1), the assumption is that the menu manager tries to
place a popup window underneath the "File" in the bar menu. It satisfies
condition a), so we have found a good position.
In the second example, 2a), the assumption is that the menu manager is trying
to place a popup window under the "Compile" in the bar menu. The first
attempt fails because the popup window is too wide to be contained entirely
in the bar menu. We then try again to see if condition b) can be satisfied.
Example 2b) shows that we can place the popup window according to condition
b), and we have found a good condition.
The other conditions, c) and d) should be self-explanatory at this point.
Remember, if you do not like the way the menu manager selects the window
position, you can either
a) specify the row and column positions of each popup menu window yourself
when calling PopupCreateMenu(), and then calling PulldownCreateMenu()
with a 0 (no adjustment) as the third argument or
b) Let the menu manager decide where to put the windows, and then adjust the
positions yourself by calling WindowMove().
Return values for PulldownCreateMenu()
--------------------------------------
If there is no error, PulldownCreateMenu() returns a valid PULLDOWN_MENU_PTR.
If there is an error, PulldownCreateMenu() returns a null PULLDOWN_MENU_PTR.
Here are the possible reasons why an error has occurred:
1) There was not enough memory to allocate for the PULLDOWN_MENU_PTR or its
internal data structures.
2) The window for the bar menu did not exist.
The first error results from a lack of heap memory. If this error occurs,
the global integer window_error_code will be set to NO_HEAP_MEM.
If the second error occurs, this is an indication that the BAR_MENU_PTR was
not created properly. Check the return values for BarCreateMenu() if this
happens. The window_error_code is set to BAD_WINDOW if this error occurs.
There is no check to see if the POPUP_MENU_PTR's are valid. It is
conceivable that there may be some entries on the bar that do not have popup
menu's under them. Therefore no check can be made for valid
POPUP_WINDOW_PTR's. It is the programmer's responsibility to check for
invalid POPUP_MENU_PTR's when creating the popup menus.
Page 227 The C Window Library Page 227
SELECTING FROM PULLDOWN MENUS
-----------------------------
The PulldownSelectMenu() function
---------------------------------
The PulldownSelectMenu() allows selection from a pulldown menu. This
function has 6 arguments. The prototype to this function is as follows:
int PulldownSelectMenu(PULLDOWN_MENU_PTR pull, int barrank,
unsigned barstart, int *poprank,
unsigned *popstart, int imm)
The first argument is a pointer to the PULLDOWN_MENU_PTR. The second
argument is the window rank of the bar menu window. The third argument is
the menu option where the bar menu should start beginning processing. If the
option is invalid or unavailable, the starting entry is the first available
entry or the first entry if the BAROVERRIDE option is on for the bar menu.
The fourth argument is an array of window ranks for each popup menu's window.
This array will correspond to each of the popup menu's windows, including
null popup menus.
Example:
int ranks[] = {1,1,1,1,1,1,1,1};
unsigned start[] = {1,1,1,1,1,1,1,1};
main() {
/* ... */
PulldownSelectMenu(pull,1,1,ranks,start,1);
}
The fifth argument is an array of starting entry numbers for each popup menu.
This array will correspond to each of the popup menus, including NULL popup
menus. The previous example illustrates how this could be done.
Immediate Mode
--------------
The last argument to PulldownSelectMenu() determines whether the menu will
start in immediate mode. Immediate mode will display the bar menu, and will
also display the popup menu defined for the bar option. If immediate mode
is desired, the last argument is a 1, otherwise it is a 0.
Page 228 The C Window Library Page 228
Values passed to the selected menu function
-------------------------------------------
When a selection is made, the menu manager will call the function defined
for the selection, and pass five arguments to this function. The first
argument passed is the PULLDOWN_MENU_PTR of the current pulldown menu. The
second argument is the BAR_MENU_PTR of the pulldown menu. The third argument
is the POPUP_MENU_PTR of the selected entry. If there is no popup menu, the
value passed for this argument is a NULL pointer. The fourth argument is the
number of the item selected on the bar menu. The fifth argument is the
number of the item selected on the popup menu.
Values returned to the menu manager
-----------------------------------
Your function must return a value back to the menu manager. There are two
possible return values, PULLDOWN_EXIT and PULLDOWN_CONTINUE.
The PULLDOWN_EXIT return value will cause the menu manager to close both the
popup menu window (if one was displayed), and the bar menu. Then control is
returned back to the function that called PulldownSelectMenu().
The PULLDOWN_CONTINUE return value will cause the menu manager to continue
processing the pulldown menu without closing the popup window (if one was
displayed).
If the return value is not one of the ones mentioned above, PULLDOWN_CONTINUE
is assumed.
Return Values for PulldownSelectMenu()
--------------------------------------
If there are no errors, PulldownSelectMenu() returns NO_ERROR.
If the bar menu window does not exist, PulldownSelectMenu() immediately
returns with BAD_WINDOW.
If the bar menu window is not open, PulldownSelectMenu() immediately returns
with WINDOW_NOT_OPEN.
Page 229 The C Window Library Page 229
REDEFINING KEY DEFINITIONS
--------------------------
The bar menu key definitions are invoked when the pulldown menu is at the bar
menu level. The popup menu keys are invoked when the pulldown menu is at the
popup menu level.
If the bar option does not have a popup menu associated with it, the bar menu
keys are always used.
Page 230 The C Window Library Page 230
REDEFINING KEY DEFINITIONS FOR POPUP MENUS
------------------------------------------
Setting Popup Menu Global Key Definitions
-----------------------------------------
In the previous sections on popup menus, there was a global array of key
definitions used for popup menus. Recall that there were 3 key definitions
that were not assigned. These definitions were POPUP_RIGHTKEY,
POPUP_LEFTKEY, and POPUP_PULLDOWN_QUIT. When a popup menu is incorporated
into a pulldown menu (after the PulldownCreateMenu() is called), the global
array popup_key_definition is assigned the default values for these
definitions. Here are the default values for the popup portion of the
pulldown menu:
Function Key Constant
-------- --- ------
Move highlight bar up Up Arrow POPUP_UPKEY
Move highlight bar down Down Arrow POPUP_DOWNKEY
Accept Menu Choice Enter POPUP_ACCEPTKEY
Escape Pop-up menu Escape POPUP_QUITKEY
Move To First Menu Item Home POPUP_HOMEKEY
Move to Last Menu Item End POPUP_ENDKEY
Move To Next Popup Menu Right Arrow POPUP_RIGHTKEY
Move to Previous Popup Menu Left Arrow POPUP_LEFTKEY
Escape Pulldown Menu Not Assigned POPUP_PULLDOWN_QUITKEY
The global array popup_key_definition contains the values of the default
popup menu key definitions. The names under the Constant heading are the
offsets in the popup_key_definition array of where the key value for the
function is defined. For instance, the value for the "Move highlight bar up"
function is located at popup_key_definition[POPUP_UPKEY]. You can change the
values in popup_key_definition at any time, but make sure that a definition
for "Escape Pop-up menu" and/or "Escape Pulldown Menu" always exists, and
that there are no duplicate definitions (i.e. the "Move highlight bar up"
key definition is the same as the "Move highlight bar down" key definition).
When defining new key values, you should use the values defined in the
keycodes.h header file for non-ascii keys.
Also note that popup_key_definition[POPUP_PULLDOWN_QUITKEY] is not assigned.
Since the key that is usually used to quit a pulldown menu is the Escape
(ESC) key, and this definition conflicts with the "Escape Popup menu", it is
better to let the programmer change the definition explicitly.
Setting Popup Menu Local Definitions
------------------------------------
You can use the PopupAssignKeys() function explained in the REDEFINING MENU
KEYS section to redefine the popup menu keys for each popup menu.
Page 231 The C Window Library Page 231
This page intentionally left blank.
Page 232 The C Window Library Page 232
REDEFINING KEY DEFINITIONS FOR THE BAR MENU
-------------------------------------------
Setting bar menu global key definitions
---------------------------------------
You can redefine the keys used to control moving the highlight bar, accepting
the menu choice, and exiting from the menu. Here is a list of the default
key mapping:
Function Key Constant
-------- --- ------
Move highlight bar right Up Arrow BAR_RIGHTKEY
Move highlight bar left Down Arrow BAR_LEFTKEY
Accept Menu Choice Enter BAR_ACCEPTKEY
Escape Bar menu (Escape Pulldown Menu) Escape BAR_QUITKEY
Move To First Menu Item Home BAR_HOMEKEY
Move to Last Menu Item End BAR_ENDKEY
The global array bar_key_definition contains the values of the default
bar menu key definitions. The names under the Constant heading are the
offsets in the bar_key_definition array of where the key value for the
function is defined. For instance, the value for the "Move highlight bar up"
function is located at bar_key_definition[BAR_RIGHTKEY]. You can change the
values in bar_key_definition at any time, but make sure that a definition
for "Escape Bar menu" always exists, and that there are no duplicate
definitions (i.e. the "Move highlight bar up" key definition is the same as
the "Move highlight bar down" key definition). When defining new key values,
you should use the values defined in the keycodes.h header file for non-ascii
keys.
Note that "Escape Bar Menu" will also escape the pulldown menu.
Setting Bar Menu Local definitions
----------------------------------
You can use the BarAssignKeys() function to redefine the bar menu keys.
Page 233 The C Window Library Page 233
PROCESSING UNDEFINED POPUP MENU KEYS
------------------------------------
Processing undefined keys is the same for regular popup menus, except that
there are 3 new return values that can be used for popup menus that are
incorporated in pulldown menus.
The popup_undef_key function pointer acts the same way as described
previously. Here are the possible values that the function pointed to by
popup_undef_key must return:
Return Action to
Value Take
------ ---------
POPUP_CONTINUE No Action. Continue processing the popup menu.
POPUP_MOVE_UP Move the highlight bar up.
POPUP_MOVE_DOWN Move the highlight bar down.
POPUP_DO_CHOICE Accept and invoke menu entry assigned to *choice.
POPUP_MOVE_CONTINUE Move the highlight bar to menu entry assigned to
*choice and continue processing menu.
POPUP_ESCAPE Escape the popup menu.
POPUP_MOVE_HOME Move highlight to first available menu entry.
POPUP_MOVE_END Move highlight to last available menu entry.
POPUP_MOVE_PAGEUP Scroll the entries in the popup window up by one
"page" (a page is the current height of the popup
window).
POPUP_MOVE_PAGEDOWN Scroll the entries in the popup window down by one
"page" (a page is the current height of the popup
window).
POPUP_MOVE_LEFT Move to next popup menu.
POPUP_MOVE_RIGHT Move to previous popup menu.
POPUP_PULLDOWN_QUIT Escape pulldown menu
Please note the new return values POPUP_MOVE_LEFT, POPUP_MOVE_RIGHT, and
POPUP_PULLDOWN_QUIT.
Page 234 The C Window Library Page 234
PROCESSING UNDEFINED BAR MENU KEYS
----------------------------------
Here are the return values that the function pointed to by bar_undef_key must
return.
Return Action to
Value Take
------ ---------
BAR_CONTINUE No Action. Continue processing the bar menu.
BAR_DO_CHOICE Accept and invoke menu entry assigned to *choice, or
display popup menu underneath bar entry.
BAR_MOVE_CONTINUE Move the highlight bar to menu entry assigned to
*choice and continue processing menu.
BAR_ESCAPE Escape the bar menu (or pulldown menu).
BAR_MOVE_LEFT Move to next bar menu entry.
BAR_MOVE_RIGHT Move to previous bar menu entry.
BAR_MOVE_HOME Move highlight to first available menu entry.
BAR_MOVE_END Move highlight to last available menu entry.
Please note that BAR_DO_CHOICE will either do the function assigned to the
bar entry assigned to *choice, or display the popup menu underneath the bar
menu entry assigned to *choice.
Page 235 The C Window Library Page 235
DISPOSING OF PULLDOWN MENUS
---------------------------
There are two functions that are used to dispose of pulldown menus. The
first is the PulldownMenuFree() function.
The PulldownMenuFree() function
-------------------------------
The PulldownMenuFree() function disposes of the PULLDOWN_MENU_PTR and returns
memory allocated back to the heap. The bar menu and the popup menus
associated with the pulldown menu remain intact.
Here is a prototype of the call to PulldownMenuFree():
int PulldownMenuFree(PULLDOWN_MENU_PTR pull)
The PulldownMenuFreeAll() function
----------------------------------
To dispose of the pulldown menu, the bar menu, and all of the popup menus,
use the PulldownMenuFreeAll() function. Here is a prototype:
int PulldownMenuFreeAll(PULLDOWN_MENU_PTR pull)
Page 236 The C Window Library Page 236
SUMMARY OF PULLDOWN MENUS
-------------------------
A pulldown menu is:
1) Made up of a bar menu and popup menus.
2) Consists of two levels, namely the bar menu level and the popup menu
level.
3) The bar menu level uses the bar menu key definitions, while the popup
menu level uses the popup menu key definitions.
4) The popup menus are initialized by using an array of POPUP_MENU_PTR's.
The order of where the popup menus are defined in this array
corresponds to each of the bar menu options.
5) A bar menu option may or may not have a popup menu defined for it.
6) When initializing a pulldown menu, you can allow the menu manager to
position the popup windows under the bar menu, or you can specify your
own positions on the screen for the popup menu windows.
7) When the menu manager calls the user written function the
PULLDOWN_MENU_PTR, BAR_MENU_PTR, POPUP_MENU_PTR, the number of the bar
entry selected, and the number of the popup selection are passed to
the user function. If there is no popup menu, the POPUP_MENU_PTR
passed is a null, and the popup selection number is 0.
8) You can open a pulldown menu from the bar level, or from the pull down
level by calling PulldownSelectMenu().
9) You can close a pulldown menu in two ways: by just disposing of the
PULLDOWN_MENU_PTR by calling PulldownMenuFree(), or disposing of all
menus used to create the pulldown menu by calling PulldownMenuFreeAll().
Page 237 The C Window Library Page 237
EXAMPLE OF PULLDOWN MENU SYSTEM
-------------------------------
Here is an example of a pulldown menu system. This program emulates the
Turbo C integrated environment.
#include "menu.h"
#define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black)
int menu_routine();
POPUP_MENU_ENTRY menu_items1[] = {
" Load F3",1,'L',F3,menu_routine,
" Pick Alt-F3",2, 'P',ALTF3,menu_routine,
" New" ,3, 'N',0,menu_routine,
" Save F2",4, 'S',F2,menu_routine,
" Write to ",5, 'W',0,menu_routine,
" Directory ",6, 'D',0,menu_routine,
" Change Dir" ,7, 'C',0,menu_routine,
" OS shell" ,8, 'O',0,menu_routine,
" Quit Alt-X" ,9,'Q',ALTX,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items3[] = {
" Run Ctrl-F9 ",1,'R',CTRLF9,menu_routine,
" Program reset Ctrl-F2 ",2,'P',CTRLF2,menu_routine,
" Go to Cursor F4 ",3,'G',F4,menu_routine,
" Trace into F7 ",4,'T',F7,menu_routine,
" Step over F8 ",5,'S',F8,menu_routine,
" User screen Alt-F5 ",6,'U',ALTF5,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items4[] = {
" Compile to OBJ ",1,'C',0,menu_routine,
" Make EXE file ",2,'M',0,menu_routine,
" Link EXE file ",3,'L',0,menu_routine,
" Build all ",4,'B',0,menu_routine,
" Primary C file: ",5,'P',0,menu_routine,
" Get info ",6,'G',0,menu_routine,
CWL_NULL,0};
Page 238 The C Window Library Page 238
POPUP_MENU_ENTRY menu_items5[] = {
" Project Name ",1,'P',0,menu_routine,
" Break make on ",2,'B',0,menu_routine,
" Auto dependencies ",3,'A',0,menu_routine,
" Clear project ",4,'C',0,menu_routine,
" Remove messages ",5,'R',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items6[] = {
" Compiler ",1,'C',0,menu_routine,
" Linker ",2,'L',0,menu_routine,
" Environment ",3,'E',0,menu_routine,
" Directories ",4,'D',0,menu_routine,
" Arguments ",5,'A',0,menu_routine,
" Save Options ",6,'S',0,menu_routine,
" Retrieve options ",7,'R',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items7[] = {
" Evaluate Ctrl-F4 ",1,'E',CTRLF4,menu_routine,
" Call Stack Ctrl-F3 ",2,'C',CTRLF3,menu_routine,
" Find Function ",3,'F',0,menu_routine,
" Refresh display ",4,'R',0,menu_routine,
" Display swapping Smart ",5,'D',0,menu_routine,
" Source debugging ",6,'S',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items8[] = {
" Add watch Ctrl-F7 ",1,'A',CTRLF7,menu_routine,
" Delete watch ",2,'D',0,menu_routine,
" Edit Watch ",3,'E',0,menu_routine,
" Remove all watches ",4,'R',0,menu_routine,
" Toggle breakpoint Ctrl-F8 ",6,'T',CTRLF8,menu_routine,
" Clear all breakpoints ",7,'C',0,menu_routine,
" View next breakpoint ",8,'V',0,menu_routine,
CWL_NULL,0};
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',0,NULLFN,
"Edit",1,10,'E',0,menu_routine,
"Run",1,17,'R',0,NULLFN,
"Compile",1,23,'C',0,NULLFN,
"Project",1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug",1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
Page 239 The C Window Library Page 239
POPUP_MENU_ENTRY *pentry[] = {menu_items1, POPUP_NULL_ENTRY,
menu_items3,
menu_items4, menu_items5, menu_items6,
menu_items7, menu_items8};
unsigned menu_colors[5]; /* Menu colors */
BAR_MENU_PTR bar; /* Pointer to bar menu */
POPUP_MENU_PTR popups[8]; /* Array of pointers to popup menus */
PULLDOWN_MENU_PTR pull; /* Pointer to pulldown menu */
WPOINTER my_open(); /* Pointer to custom bar window open function */
unsigned int popuprank[] = {1,1,1,1,1,1,1,1}; /* Ranks of popup windows */
int popupstart[] = {1,1,1,1,1,1,1,1}; /* Starting option for each popup
menu */
int height[] = {9,0,6,6,5,7,6,8}; /* height of each window */
WPOINTER pw; /* Misc. windows, not part of menu
system */
char *line =
"─────────────────────────────"; /* Horizontal line */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
pw = WindowInitialize(BORDER,5,10,70,5,BLACKONWHITE,BLACKONWHITE,
SINGLEBOX);
WindowOpen(pw);
/* define colors */
menu_colors[0] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[1] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[2] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[3] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[4] = CREATE_VIDEO_ATTRIBUTE(white,black);
bar = BarCreateMenu(bar_items, /* Array of BAR_MENU_ENTRY's */
menu_colors,/* Pointer to menu colors */
6, /* Row to open bar menu window */
1, /* Column to open bar menu window */
BARWRAP | BARSTATIC,
my_open); /* Customized window open function */
/* Now loop to create all popup menus
Be careful and assign NULL to the second popup menu */
Page 240 The C Window Library Page 240
for (i=0; i<8; i++) /* Loop for all popup menus */
{
if (pentry[i] != POPUP_NULL_ENTRY) /* Skip over NULL popup entry */
{
popups[i] =
PopupCreateMenu(pentry[i], /* Array of POPUP_MENU_ENTRY's */
menu_colors, /* Array of menu colors, */
/* The next two arguments will later be ignored */
1, /* Row to open popup window on */
1, /* Column to open popup */
height[i], /* height of the popup window */
/* No custom window open
functions */
POPUPWRAP | POPUPSTATIC, /* wrap the window */
WNULLFN,
VWNULLFN);
/* Now set the popup menu options */
}
else
popups[i] = (POPUP_MENU_PTR)0; /* Make this a null POPUP_MENU_PTR */
} /* end for (i=0 ... */
VirtualWriteString(POPUP_VIRTUAL_WINDOW(popups[7]),line,5,1);
PopupMakeEntryUnavailable(popups[6],2); /* hide 2nd and 3rd entries in */
PopupMakeEntryUnavailable(popups[6],3); /* popups[6] */
PopupSetOptions(popups[6],POPUPOVERRIDE,1);
pull = PulldownCreateMenu(popups,bar,1);
PulldownSelectMenu(pull,1,1,popuprank,popupstart,1);
PulldownMenuFree(pull);
}
int menu_routine(PULLDOWN_MENU_PTR p, BAR_MENU_PTR b,
POPUP_MENU_PTR pop,
unsigned int hs, unsigned int vs)
{
int ch;
WindowClear(pw);
WindowPrintf(pw,
"You have selected bar option %s\npopup option %s\n",
BAR_ENTRY_STRING(b,hs),POPUP_ENTRY_STRING(pop,vs));
WindowWriteCenterString(pw,"Press Escape to Quit",3);
WindowWriteCenterString(pw,"Press any other key to continue...",4);
WindowDisplay(pw,1,NOEFFECT);
ch = GET_KEY();
WindowHide(pw,NOEFFECT);
if (ch == ESC)
return PULLDOWN_EXIT;
return PULLDOWN_CONTINUE;
}
Page 241 The C Window Library Page 241
WPOINTER my_open() /* Custom window open function for bar menu */
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE,BLACKONWHITE,"");
WindowOpen(w);
return w;
}
Page 242 The C Window Library Page 242
MISCELLANEOUS FUNCTIONS
-----------------------
There are other functions in The C Window Library that you can use without
defining windows.
SETTING AND CHECKING VIDEO PAGES
--------------------------------
The following functions sets and checks video pages. Your video setup must
support multiple video pages for the examples given in this section to work.
Please refer to page 5 for a discussion of video adapters and the number
of pages each will support.
CheckVideoPage()
----------------
This function checks to see if the video page is valid. Here is the
prototype:
int CheckVideoPage(int page)
If page is valid, CheckVideoPage() returns NO_ERROR. If it is not, the return
value is INVALID_PAGE.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
for (i=0;i<8;i++)
{
if (CheckVideoPage(i) == NO_ERROR)
printf("\nValid video page #%d",i);
else
printf("\nInvalid video page #%d",i);
}
}
Page 243 The C Window Library Page 243
SetActiveVideoPage() function
-----------------------------
The SetActiveVideoPage() function sets the active video page. Here is a
prototype:
int SetActiveVideoPage(int page)
Any windows initialized with WindowInitialize() will have its output directed
to the current active video page on initialization. This function DOES NOT
change the visible display page.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w1, w2;
main()
{
WindowInitializeSystem();
/* Save Base Screen for video pages 0 and 1 */
WindowSaveInitial(0);
WindowSaveInitial(1);
/* Set the active video page */
SetActiveVideoPage(0);
w1 = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
SetActiveVideoPage(1);
w2 = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX);
}
The above example shows two windows, w1 and w2, being open on different video
pages. Please note the two calls to WindowSaveInitial(). The first saves
the base screen on video page 0, and the second call saves the initial screen
on page 1. The first call to SetActiveVideoPage() sets the active video page
to page 0. This is usually the active video page on startup. Since the
active page is 0, w1 is opened with page 0 as its video page. The second
call to SetActiveVideoPage() makes page 1 the active page, therefore w2 is
initialized to send its output to video page 1.
If there are no errors, SetActiveVideoPage() returns NO_ERROR.
If there are errors, SetActiveVideoPage() returns INVALID_PAGE if the video
page is invalid.
Page 244 The C Window Library Page 244
SetVisibleVideoPage() function
------------------------------
The SetVisibleVideoPage() function sets the visible video page. Here is a
prototype:
int SetVisibleVideoPage(int page)
The visible video page is the page displayed on the screen.
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w1,w2;
main()
{
WindowInitializeSystem();
/* Make sure video page is 0 */
SetVisibleVideoPage(0);
SetActiveVideoPage(0);
/*Save Base screen for video pages 0 and 1 */
WindowSaveInitial(0);
WindowSaveInitial(1);
/* Initialize Windows */
w1 = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
SetActiveVideoPage(1);
w2 = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w1);
WindowOpen(w2);
WindowWriteString(w1,"This is window 1 on page 0",1,1);
WindowWriteString(w2,"This is window 2 on page 1",1,1);
/* Display video page 0 */
WindowDisplay(w1,1,NOEFFECT);
GET_KEY();
/* Change to video page 1 and display */
SetVisibleVideoPage(1);
WindowDisplay(w2,1,NOEFFECT);
GET_KEY();
/* Reset to page 0 */
SetVisibleVideoPage(0);
}
Page 245 The C Window Library Page 245
The example above initializes two windows. w1 is initialized on page 0 and
w2 is initialized on page 1. Also note that there are two calls to
WindowSaveInitial(), one for page 0 and another for page 1. The first window
displayed is w1. Once a key is pressed the visible page is switched to page
1 by calling SetVisibleVideoPage(). The last line of the program sets the
visible page back to page 0. You should do this on exit of any program that
changes video pages.
If there are no errors, SetVisibleVideoPage() returns NO_ERROR.
If there are errors, SetVisibleVideoPage() returns INVALID_PAGE if the video
page is invalid.
Page 246 The C Window Library Page 246
GENERAL STRING WRITING FUNCTIONS
--------------------------------
The following functions write strings to the active video page. These
functions are not window functions, therefore you should use these functions
when you are not using windows created with The C Window Library unless you
are careful in using them. The advantage of using these functions instead of
the normal string writing functions found in most C compiler libraries (i.e.
printf(), puts(), etc.) is that the output is written directly to screen
memory, which results in fast output. If the BIOS option is selected, BIOS
functions are used to write the strings. Refer to page 4 for a discussion of
direct screen writing and BIOS functions.
VideoWriteString()
------------------
This function writes a null terminated string to the active video page. Here
is the prototype:
void VideoWriteString(char *string, int row, int col)
The first argument is the string, and the second and third arguments are the
(row,col) position of the active video page to place the string. There is no
check to see if (row,col) is out of bounds. The attribute that is used is
determined by the current video attribute at each character position on the
screen.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteString("Hello, World",i,1);
}
There is no return value for VideoWriteString().
Page 247 The C Window Library Page 247
VideoWriteStringAttr()
----------------------
This function writes a null terminated string to the active video page using
a video attribute. Here is the prototype:
void VideoWriteStringAttr(char *string, int row, int col, int attr)
The first argument is the string, the second and third arguments are the
(row,col) position of the active video page to place the string, and the
last argument is the video attribute to use. There is no check to see if
(row,col) is out of bounds. The last argument is the video attribute to use.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteStringAttr("Hello, World",i,1,REVERSE);
}
There is no return value for VideoWriteStringAttr().
VideoWriteAttributes()
----------------------
This function writes a string of attributes to the active video page.
Here is the prototype:
void VideoWriteAttributes(char *buffer, int row, int col, int num)
The first argument is the buffer that contains the video attributes. The
second and third arguments are the (row,col) position of the active video
page to place the attributes, and the last arguments is the number of
attributes to write from the buffer. There is no check to see if (row,col)
is out of bounds, or if num attributes will exceed the right edge of the
screen.
Page 248 The C Window Library Page 248
Example:
#include "window.h"
#include <string.h>
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
char buf[12];
main()
{
WindowInitializeSystem();
VideoWriteString("Hello, World",1,1);
GET_KEY();
memset(buf,REVERSE,sizeof(buf));
VideoWriteAttributes(buf,1,1,sizeof(buf));
}
The example above writes a string using the VideoWriteString() function and
then changes the attribute of the string by setting a buffer to the REVERSE
attribute and using the VideoWriteAttributes() function with this buffer.
There is no return value for VideoWriteAttributes().
VideoWriteCenterString()
------------------------
The VideoWriteCenterString() function centers a string at a certain row of
the active video page. Here is the prototype:
void VideoWriteCenterString(char *string, int row)
The first argument is the string and the second argument is the row to write
on the active video page to write the string. There is no check to see if
row is out of bounds.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteCenterString("Hello, World",i);
}
There is no return value for VideoWriteCenterString().
Page 249 The C Window Library Page 249
VideoWriteCenterStringAttr()
----------------------------
The VideoWriteCenterStringAttr() function centers a string at a certain row
of the active video page with a specified video attribute. Here is the
prototype:
void VideoWriteCenterStringAttr(char *string, int row, int attr)
The first argument is the string and the second argument is the row to write
on the active video page to write the string. The third argument is the
video attribute to use. There is no check to see if row is out of bounds.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
for (i=1;i<=10;i++)
VideoWriteCenterStringAttr("Hello, World",i,REVERSE);
}
There is no return value for VideoWriteCenterStringAttr().
VideoWriteCharAndAttr()
-----------------------
The VideoWriteCharAndAttr() function writes a string of character-attribute
pairs to the active video page. Here is the prototype:
void VideoWriteCharAndAttr(char *buffer, int row, int col, int num)
The first argument is the buffer that holds the character attribute pairs.
This buffer should be in the following form:
-----------------------------------------------
|char1 | attr1 | char2 | attr2 | char3 | attr3| ...
-----------------------------------------------
The second and third arguments are the (row,col) position of the active video
page to write the string. The last argument is the number of
character-attribute pairs to write.
Page 250 The C Window Library Page 250
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
char buf[24];
main()
{
int i,j;
WindowInitializeSystem();
for (i=0,j='A'; i<24; i+=2,j++)
{
buf[i] = j;
buf[i+1] = REVERSE;
}
for (i=1;i<=10;i++)
VideoWriteCharAndAttr(buf,i,1,12);
}
The example above creates a string of character attribute pairs and then
writes this string using the VideoWriteCharAndAttr() function.
There is no return value for VideoWriteCharAndAttr().
VideoWriteStringCC()
--------------------
This function writes a string centered around a column on the active video
page. Here is the prototype:
void VideoWriteStringCC(char *string, int row, int col)
The first argument is the string. The second argument is the row, and the
third argument is the column to center the string around.
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringCC("This",1,10);
VideoWriteStringCC("is",2,10);
VideoWriteStringCC("centered",3,10);
VideoWriteStringCC("around",4,10);
VideoWriteStringCC("column",5,10);
VideoWriteStringCC("10",6,10);
}
There is no return value for VideoWriteStringCC().
Page 251 The C Window Library Page 251
VideoWriteStringCCAttr()
------------------------
This function writes a string centered around a column on the active video
page with a specified video attribute. Here is the prototype:
void VideoWriteStringCCAttr(char *string, int row, int col, int attr)
The first argument is the string. The second argument is the row. The third
argument is the column to center the string around, and the fourth argument
is the attribute to use.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringCCAttr("This",1,10,REVERSE);
VideoWriteStringCCAttr("is",2,10,REVERSE);
VideoWriteStringCCAttr("centered",3,10,REVERSE);
VideoWriteStringCCAttr("around",4,10,REVERSE);
VideoWriteStringCCAttr("column",5,10,REVERSE);
VideoWriteStringCCAttr("10",6,10,REVERSE);
}
There is no return value for VideoWriteStringCCAttr().
VideoWriteStringRJ()
--------------------
The VideoWriteStringRJ() function writes a string to the screen that is right
justified at column col. If the string will not fit within column 1, the
string is still right justified, but excess characters to the left of column
1 are clipped. This function writes a string column on the active video
page. Here is the prototype:
void VideoWriteStringRJ(char *string, int row, int col)
The first argument is the string. The second argument is the row, and the
third argument is the column to right justify the string on.
Page 252 The C Window Library Page 252
Example:
#include "window.h"
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringRJ("This",1,10);
VideoWriteStringRJ("is",2,10);
VideoWriteStringRJ("right",3,10);
VideoWriteStringRJ("justified",4,10);
VideoWriteStringRJ("on ",5,10);
VideoWriteStringRJ("column",6,10);
VideoWriteStringRJ("10",7,10);
}
There is no return value for VideoWriteStringRJ().
VideoWriteStringRJAttr()
------------------------
The VideoWriteStringRJAttr() function writes a string to the screen that is
right justified at column col with a specified video attribute. If the
string will not fit within column 1, the string is still right justified, but
excess characters to the left of column 1 are clipped. This function writes
a string column on the active video page. Here is the prototype:
void VideoWriteStringRJAttr(char *string, int row, int col, int attr)
The first argument is the string. The second argument is the row. The third
argument is the column to right justify the string on, and the last argument
is the video attribute to use.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
main()
{
int i;
WindowInitializeSystem();
VideoWriteStringRJAttr("This",1,10,REVERSE);
VideoWriteStringRJAttr("is",2,10,REVERSE);
VideoWriteStringRJAttr("right",3,10,REVERSE);
VideoWriteStringRJAttr("justified",4,10,REVERSE);
VideoWriteStringRJAttr("on ",5,10,REVERSE);
VideoWriteStringRJAttr("column",6,10,REVERSE);
VideoWriteStringRJAttr("10",7,10,REVERSE);
}
There is no return value for VideoWriteStringRJAttr().
Page 253 The C Window Library Page 253
VideoPrintf()
-------------
The VideoPrintf() function writes formatted strings to the active video page.
This function works exactly the same as printf() except that output is
written directly to the screen. Here is the prototype:
void VideoPrintf(char *format [,arg1,arg2...])
The location of the output is placed at the current cursor position. The
cursor is advanced to one character beyond the last character of output.
Example:
#include "window.h"
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
VideoPrintf("3+2 is equal to %d\n",3+2);
VideoPrintf("i is equal to %d\nj is equal to %lf\n",i,j);
}
Unlike printf(), there is no return value with VideoPrintf().
VideoPrintfAttr()
-----------------
The VideoPrintfAttr() function works the same as VideoPrintf() except that a
video attribute is specified. Here is the prototype:
void VideoPrintfAttr(int attr, char *format [,arg1,arg2...])
The first argument is the attribute to use. The second argument is the
format string, and the other arguments are optional arguments.
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black)
int i = 3;
double j = 5.6;
main()
{
WindowInitializeSystem();
VideoPrintfAttr(REVERSE,"3+2 is equal to %d\n",3+2);
VideoPrintfAttr(REVERSE,"i is equal to %d\nj is equal to %lf\n",i,j);
}
Unlike printf(), there is no return value with VideoPrintfAttr().
Page 254 The C Window Library Page 254
READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN
-------------------------------------------------
These functions read characters and/or attributes from the active video page.
VideoReadCharacters()
---------------------
This function reads characters from the active video page into a buffer.
Here is the prototype:
void VideoReadCharacters(char *buffer, int row, int col, int num)
The first argument is the buffer to store the characters. The second and
third arguments are the (row,col) position on the active video page. The
last argument is the number of characters to read in. There is no check to
see if the row, col, or the num arguments are in bounds of the screen.
Example:
#include "window.h"
char buf[25];
main()
{
WindowInitializeSystem();
VideoReadCharacters(buf,1,1,25);
}
The example above reads the characters on the screen starting at position
(1,1).
There is no return value for VideoReadCharacters().
VideoReadAttributes()
---------------------
This function reads attributes from the active video page into a buffer.
Here is the prototype:
void VideoReadAttributes(char *buffer, int row, int col, int num)
The first argument is the buffer to store the attributes. The second and
third arguments are the (row,col) position on the active video page. The
last argument is the number of attributes to read in. There is no check to
see if the row, col, or the num arguments are in bounds of the screen.
Page 255 The C Window Library Page 255
Example:
#include "window.h"
char buf[25];
main()
{
WindowInitializeSystem();
VideoReadAttributes(buf,1,1,25);
}
The example above reads the attributes on the screen starting at position
(1,1).
There is no return value for VideoReadAttributes().
VideoReadCharAndAttr()
----------------------
This function reads character-attribute pairs from the active video page
into a buffer. Here is the prototype:
void VideoReadCharAndAttr(char *buffer, int row, int col, int num)
The first argument is the buffer to store the character-attribute pairs. The
second and third arguments are the (row,col) position on the active video
page. The last argument is the number of character-attribute pairs to read
in. There is no check to see if the row, col, or the num arguments are in
bounds of the screen.
Example:
#include "window.h"
char buf[26];
main()
{
WindowInitializeSystem();
VideoReadCharAndAttr(buf,1,1,13);
}
The example above reads the character-attribute pairs on the screen starting
at position (1,1).
There is no return value for VideoReadCharAndAttr().
Page 256 The C Window Library Page 256
DRAWING BOXES
-------------
The following functions draw boxes on the screen.
VideoDrawBox()
--------------
The VideoDrawBox() function draws a box on the screen. Here is the
prototype:
void VideoDrawBox(int urow, int ucol, int lrow, int lcol, char *boxchars)
The box is defined by a rectangular region. The urow and ucol arguments are
the coordinates of the upper left hand corner of the box. The lrow and lcol
arguments are the coordinates of the lower right hand corner of the box. The
last argument is a string of box drawing characters to use. You can use the
predefined box types in the header file vidsys.h, or you can make your own.
Refer to page 11 for more information on box types.
There is no check to see if the coordinates are in bounds.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
/* Draw two boxes */
VideoDrawBox(1,1,10,10,SINGLEBOX);
VideoDrawBox(1,11,10,21,DOUBLEBOX);
}
There is no return value for VideoDrawBox().
VideoDrawBoxAttr()
------------------
The VideoDrawBoxAttr() function draws a box on the screen with a specified
video attribute. Here is the prototype:
void VideoDrawBoxAttr(int urow, int ucol, int lrow, int lcol, char *boxchars,
int attr)
This function works the same way as the VideoDrawBox() function. Note that
the last argument is the video attribute to use. There is no check to see if
the coordinates are in bounds.
Page 257 The C Window Library Page 257
Example:
#include "window.h"
#define REVERSE CREATE_VIDEO_ATTRIBUTE(black,white)
main()
{
WindowInitializeSystem();
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
/* Draw two boxes */
VideoDrawBoxAttr(1,1,10,10,SINGLEBOX,REVERSE);
VideoDrawBoxAttr(1,11,10,21,DOUBLEBOX,REVERSE);
}
There is no return value for VideoDrawBoxAttr().
Page 258 The C Window Library Page 258
SAVING AND RESTORING SCREEN IMAGES
----------------------------------
The following functions save rectangular regions of the screen in a buffer,
and restore rectangular portions of the screen. These routines exist in The
C Window Library so that advanced C programmers can have general screen
saving/restoring routines handy. As always, you should be careful in using
these functions at the same time you are using windows created with The C
Window Library.
VideoSave()
-----------
The VideoSave() function saves a rectangular portion of the screen into a
structure called a VBLOCK. A pointer to this structure is called a
VBLOCKPTR. Here is the prototype:
VBLOCKPTR VideoSave(int urow, int ucol, int lrow, int lcol)
This function returns a VBLOCKPTR. The VBLOCKPTR will be used to move or
restore this saved region. The first two arguments are the coordinates of
the upper left hand corner of the rectangle to save (urow,ucol). The last
two arguments are the coordinates of the lower right hand corner of the
rectangle (lrow,lcol). There is no check to see if the coordinates are out
of bounds. You can use this function to save the base screen, and then use
VideoRestore() to restore the base screen on exit.
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,25,80); /* Save Rectangular region */
/* Check if NULL */
if (v == (VBLOCKPTR)0)
VideoWriteString("Trouble saving video");
}
If there are no errors, VideoSave() returns a valid VBLOCKPTR.
If there are errors VideoSave() returns a null VBLOCKPTR and sets the global
integer window_error_code to the following value:
NO_HEAP_MEM if there is not enough memory for the save buffer of the
VBLOCKPTR.
Page 259 The C Window Library Page 259
VideoMove()
-----------
The VideoMove() function moves a region saved by VideoSave() to a different
location of the screen. This location will be the new upper left hand corner
of the rectangular region that was saved. The move is not displayed until
you call VideoRestore(), which is defined later. Here is the prototype:
void VideoMove(VBLOCKPTR v, int row, int col)
The first argument is the VBLOCKPTR. The second and third arguments are the
new upper left hand position of the saved area. There is NO check to see if
the VBLOCKPTR exists, or the row or column are valid.
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,10,10); /* Save Rectangular region defined by (1,1)
(10,10) */
VideoMove(v,1,10);
}
There is no return value for VideoMove().
VideoRestore()
--------------
The VideoRestore() function takes a rectangular area of the screen saved with
VideoSave() and redisplays the area. Here is the prototype:
void VideoRestore(VBLOCKPTR v)
The only argument is the VBLOCKPTR. There is no check to see if the
VBLOCKPTR is valid.
Page 260 The C Window Library Page 260
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,10,10);
for (i=1;i<=10;i++)
VideoWriteString("This is the save area. Press a key to restore.",i,1);
GET_KEY();
VideoRestore(v);
}
There is no return value for VideoRestore().
VideoFree()
-----------
The VideoFree() function frees a previously defined VBLOCKPTR. Here is the
prototype:
void VideoFree(VBLOCKPTR v)
The only argument is the VBLOCKPTR. There is NO check to see if the
VBLOCKPTR is valid, therefore you must be very careful to call this function
on a valid VBLOCKPTR. If not, the heap will become corrupted.
Example:
#include "window.h"
VBLOCKPTR v;
main()
{
WindowInitializeSystem();
v = VideoSave(1,1,10,10);
for (i=1;i<=10;i++)
VideoWriteString("This is the save area. Press a key to restore.",i,1);
GET_KEY();
VideoRestore(v);
VideoFree(v);
}
There is no return value for VideoFree().
Page 261 The C Window Library Page 261
CLEARING SCREENS
----------------
The following functions clears the visible video page, and clears regions of
the visible screen.
ClearScreen()
-------------
The ClearScreen() function clears the visible video page with a specified
attribute and moves the screen cursor to position (1,1). Here is the
prototype:
void ClearScreen(int attr)
The only argument is the video attribute to use.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
/* Clear the entire screen */
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ClearScreen().
ClearRegion()
-------------
This function clears a rectangular region of the screen. Here is the
prototype:
void ClearRegion(int urow, int ucol, int lrow, int lcol, int attr)
The first two arguments represent the coordinate of the upper left hand
coordinates of the rectangular region to clear. The third and fourth
arguments represent the coordinate of the lower right hand corner of the
rectangular region. The last argument is the attribute to use. There is no
check to see if the coordinates are in bounds.
Page 262 The C Window Library Page 262
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
/* Clear Region defined by (1,1) as the upper right hand corner and (10,10)
as the lower right hand corner */
ClearRegion(1,1,10,10,CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ClearRegion().
Page 263 The C Window Library Page 263
SCROLLING SCREENS
-----------------
These functions scroll portions of the screen up or down.
ScrollScreenUp()
----------------
The ScrollScreenUp() function scrolls a rectangular portion of the screen up
a specified number of lines. Here is the prototype:
void ScrollScreenUp(int numlines, int urow, int ucol, int lrow, int lcol,
int attr)
The first argument is the number of lines to scroll the region. The second
and third arguments are the (row,col) coordinates of the upper left hand
corner of the rectangular region to scroll. The fourth and fifth arguments
are the (row,col) of the lower right hand corner of the rectangular region.
The last argument is the attribute to use for blank lines created when the
region is scrolled.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ScrollScreenUp(1,1,3,5,10,CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ScrollScreenUp().
ScrollScreenDown()
------------------
The ScrollScreenDown() function scrolls a rectangular portion of the screen
down a specified number of lines. Here is the prototype:
void ScrollScreenDown(int numlines, int urow, int ucol, int lrow, int lcol,
int attr)
The first argument is the number of lines to scroll the region. The second
and third arguments are the (row,col) coordinates of the upper left hand
corner of the rectangular region to scroll. The fourth and fifth arguments
are the (row,col) of the lower right hand corner of the rectangular region.
The last argument is the attribute to use for blank lines created when the
region is scrolled.
Page 264 The C Window Library Page 264
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ScrollScreenDown(1,1,3,5,10,CREATE_VIDEO_ATTRIBUTE(black,white));
}
There is no return value for ScrollScreenDown().
Page 265 The C Window Library Page 265
CHANGING THE VIDEO MODE
-----------------------
With The C Window Library, you can change the video mode at any time. The
video mode determines the width of the screen, and whether the screen is in
text or graphics mode.
SetVideoMode()
--------------
The SetVideoMode() function changes the video mode. Here is a prototype:
void SetVideoMode(int modenum)
The only argument is the mode number. Refer to the Video Paging section on
page 5 for more information on mode numbers and what they display.
When the video mode is changed, the screen is cleared. This cannot be
prevented. You must redisplay any windows that were on the screen. If the
change of video mode results in a change in screen dimensions, then you must
read the following sections on CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE
SCREEN. Even though The C Window Library does not support graphics mode, you
can change to graphics mode in The C Window Library,
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
SetVideoMode(3); /* Change to video mode 3 */
}
There is no return value for SetVideoMode().
Page 266 The C Window Library Page 266
CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN
-----------------------------------------------------
Changing rows
-------------
With The C Window Library, you can change the number of rows on the video
screen. However, there are some things to watch out for when changing the
number of rows, especially if you have windows displayed on the screen. If
you are not using any window related functions, you can change the number of
displayable rows safely by doing two things:
a) Call the SetVideoRows() function to change the number of rows.
b) Call AdjustGlobalData() to adjust the global variables used by The C
Window Library that keep track of the screen dimensions.
If you are going to create or have created windows you must do three things:
a) Make sure that any window defined will have valid coordinates when the
number of rows are changed. There may be cases where a window occupies a
row that exists in one screen mode, but the row does not exist in another
screen mode. If there are windows that will have invalid coordinates in
another screen configuration, you must resize them, remove them, or
whatever it takes to resolve the invalid coordinates.
b) Call the SetVideoRows() function.
c) Call the AdjustScreenInfo() function. This function adjusts all global
variables defined in The C Window Library to reflect the new number of
rows.
Whether there are or are not windows defined, the visible video page MUST be
page 0 before changing the number of screen rows.
AdjustScreenInfo()
------------------
This function must be called after SetVideoRows() is called if you are
going to, or have initialized and/or displayed windows. Here is the
prototype:
int AdjustScreenInfo(int page)
The only argument is the video page to adjust to the new screen height.
Because of the new dimension of the screen, there has to be a reshuffling of
a few global arrays, constants, variables, etc. The AdjustScreenInfo()
function does just this. If you do not call AdjustScreenInfo(), you may see
problems if you try to manipulate windows on the new screen.
Page 267 The C Window Library Page 267
See SetVideoRows() for an example of AdjustScreenInfo().
If there are no errors, AdjustScreenInfo() returns NO_ERROR.
If there are errors, AdjustScreenInfo() returns the following value:
NO_HEAP_MEM if there is not enough memory to allocate for the global arrays,
structures, etc.
AdjustGlobalData()
------------------
The AdjustGlobalData() function should be called after you have changed the
number of video rows using SetVideoRows() (defined below). This resets the
global variables necessary for non-window functions to execute properly.
Here is the prototype:
void AdjustGlobalData(void)
There are no arguments and no return value for AdjustGlobalData(). If you
have called AdjustScreenInfo(), you do not have to call AdjustGlobalData().
See below for an example of AdjustGlobalData().
SetVideoRows()
--------------
The SetVideoRows() function changes the number of video rows on the screen.
Here is a list of video adapters and there row number capabilities:
Video Type Number of Rows
Possible
---------- --------------
CGA, MDA, Hercules 25
EGA 25, 43
MCGA 25, 50
VGA 12, 14, 21, 25, 28, 43, 50
The list above are the values SetVideoRows() uses, depending on the adapter
that The C Window Library has detected. If your video card supports a row
configuration that is not supported by the SetVideoRows() function, consult
the 'Changing columns' section and proceed as if you are changing the number
of columns.
Page 268 The C Window Library Page 268
Here is the prototype for SetVideoRows():
int SetVideoRows(int numrows, int modeflag)
The first argument is the number of screen rows. The modeflag tells whether
the video mode should be reset. If modeflag is 0, the video mode is not
reset. Any other value for modeflag will cause a video mode reset. This
reset may or may not be necessary, so experiment with both values for
modeflag.
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
VideoWriteString("Press a key to change to a new video mode",1,1);
GET_KEY();
if (VGA_MODE_ON || MCGA_MODE_ON)
SetVideoRows(50,0);
else
if (EGA_MODE_ON)
SetVideoRows(43,0);
else
{
VideoWriteString("Hardware does not support changing video rows",2,1);
exit(0);
}
AdjustGlobalData();
VideoWriteString("Press a key again to change to 25 lines",2,1);
GET_KEY();
SetVideoRows(25,0);
AdjustGlobalData();
}
The example above uses the constants VGA_MODE_ON, MCGA_MODE_ON, and
EGA_MODE_ON. These constants are discussed in the VIDEO MACROS section.
Here is another example, but now we have a window on the screen.
Page 269 The C Window Library Page 269
Example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to change rows",1,1);
GET_KEY();
if (VGA_MODE_ON || MCGA_MODE_ON)
SetVideoRows(50,0);
else
if (EGA_MODE_ON)
SetVideoRows(43,0);
else
{
WindowWriteString(w,"Cannot change rows",1,1);
exit(0);
}
/* Adjust the screen information */
AdjustScreenInfo(0);
/* OK to adjust to new height */
WindowResizeHeight(w,40,ANCHORTOP);
WindowWriteString(w,"Now press a key to change back",2,1);
GET_KEY();
/* First we must resize window */
WindowResizeHeight(w,10,ANCHORTOP);
SetVideoRows(25,0);
AdjustScreenInfo(0);
}
Note the use of AdjustScreenInfo() after a reset is made.
If there are no errors, SetVideoRows() returns no errors.
If there are errors SetVideoRows() returns the following value:
INVALID_ROWS if the number of rows is not supported for the detected monitor
type.
Page 270 The C Window Library Page 270
Changing columns
----------------
The number of columns can be changed, but there are two things to watch out
for. First, to change from 40 column mode to 80 column mode or vice-versa,
is a matter of changing the video mode. Changing the video mode from 40 to
80 column mode or from 80 to 40 requires a BIOS function that is present on
all systems that support 40 column mode.
40 column and 80 column modes
-----------------------------
To change to 40 column mode do the following:
SetVideoMode(0); /* this changes to 40 column black and white mode */
or
SetVideoMode(1); /* this changes to 40 column color mode */
The example above only works if you have a CGA, EGA, MCGA, or VGA card.
To change to 80 column mode do the following:
SetVideoMode(2); /* this changes to Black and White 80 column mode */
or
SetVideoMode(3); /* use this for color 80 column mode */
or
SetVideoMode(7); /* use this for mono cards */
SetVideoMode(7) works for all adapters, while SetVideoMode(2) and
SetVideoMode(3) works only for CGA, EGA, MCGA, or VGA cards.
Modes higher than 80 columns
----------------------------
There are video systems that support video modes greater than 80 columns.
The problem is that for each different brand of video adapter, there is a
unique way of changing to a higher column mode. Most of these adapters
support an additional BIOS function that must be called to change to any
screen column mode higher than 80. Therefore, it is up to you (the
programmer) to find out how to change the video system from 80 columns to a
higher column mode. Once you are familiar with how to do this, changing the
number of columns is almost the same as changing the number of rows.
Page 271 The C Window Library Page 271
If you are using any window related functions, you can change the number
of displayable columns safely by doing three things:
a) Call the appropriate routine to change the number of columns. If this is
a call to SetVideoMode(), the screen will be cleared.
b) Call AdjustScreenInfo() to adjust the global variables used by The C
Window Library that keep track of the screen dimensions.
c) Readjust and/or redraw any windows on the screen. Make sure that all
windows fit on the screen, whether they are hidden or not.
If you are not using any windows in your application, replace the call to
AdjustScreenInfo() in step b) with a call to AdjustGlobalData().
This example works for the ATI VGA card. This changes the mode to 132
columns:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
WPOINTER w;
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX);
WindowOpen(w);
WindowDisplay(w,1,NOEFFECT);
WindowWriteString(w,"Press a key to change columns",1,1);
GET_KEY();
/* Set Video Mode to 132 rows x 25 columns (Works for ATI VGA card) */
SetVideoMode(0x23);
/* Adjust the screen information and redisplay window */
AdjustScreenInfo(0);
WindowDisplay(w,1,NOEFFECT);
/* OK to adjust to new height */
WindowResizeWidth(w,100,ANCHORLEFT);
WindowWriteString(w,"Now press a key to change back",2,1);
GET_KEY();
/* First we must resize window */
WindowResizeWidth(w,30,ANCHORLEFT);
/* Set back to 80 column mode */
SetVideoMode(3);
AdjustScreenInfo(0);
WindowDisplay(w,1,NOEFFECT);
}
Page 272 The C Window Library Page 272
CURSOR MANIPULATION
-------------------
The functions defined in this section manipulate the cursor. The
following functions can be called without calling WindowInitializeSystem().
MoveCursor()
------------
This function moves the cursor to a different location. Here is the
prototype:
void MoveCursor(int row, int col, int page)
The first two arguments are the row and column positions of where to move the
cursor. The last argument is the video page of the cursor you want to move.
Example:
#include "window.h"
main()
{
MoveCursor(1,5,0); /* Move cursor to row 1 column 5 on video page 0 */
}
There is no return value for MoveCursor().
ChangeCursor()
--------------
The ChangeCursor() function changes the shape of the cursor. The shape of
the cursor is determined by its starting and ending scan lines. Here is a
prototype:
void ChangeCursor(unsigned startline, unsigned endline)
The first argument is the starting scan line and the second argument is the
ending scan line. For monochrome systems, there are 12 scan lines numbered 0
thru 11, while on color systems there are 8 scan lines numbered 0 thru 7.
The starting scan line is the top line of the cursor, and the ending scan
line is the last line of the cursor. There is no check to see if the
starting scan line and the ending scan lines are valid.
Page 273 The C Window Library Page 273
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
ChangeCursor(6,7); /* This is an underline cursor */
GET_KEY();
ChangeCursor(0,7); /* This is a thick cursor */
}
There is no return for ChangeCursor().
GetCursorShape()
----------------
This function returns the shape of the cursor in scan lines. Here is the
prototype:
void GetCursorShape(unsigned *startline, unsigned *endline)
When this function returns, the staring scan line is placed in the integer
pointed to by scanline, and the ending scan line is placed in the integer
pointed to by endline.
Example:
#include "window.h"
main()
{
int start, end;
WindowInitializeSystem();
GetCursorShape(&start, &end);
VideoPrintf("\nThe starting scan line is %d\nThe ending scan line is %d",
start,end);
}
There is no return value for GetCursorShape().
GetCursorPosition()
-------------------
This function gets the current cursor position. Here is the prototype:
void GetCursorPosition(int *row, int *col, int page)
Page 274 The C Window Library Page 274
The first argument is a pointer to an integer that will be set to the current
row. The second argument is a pointer to an integer that will be set to the
current column. The last argument is the video page of the cursor.
Example:
#include "window.h"
main()
{
int row,col;
MoveCursor(10,15);
GetCursorPosition(&row,&col,0);
WindowInitializeSystem();
VideoPrintf("\nThe row of the cursor is %d\nThe column is %d",
row,col);
}
There is no return value for GetCursorPosition().
The following functions serve as shortcuts in changing the cursor shape.
HideCursor()
------------
Hides the cursor on the screen. Here is the prototype:
void HideCursor(void)
BlockCursor()
-------------
Displays the cursor as a thick block.
void BlockCursor(void)
ThinCursor()
------------
Displays the cursor as an underline cursor.
void ThinCursor(void)
Page 275 The C Window Library Page 275
Example:
#include "window.h"
main()
{
WindowInitializeSystem();
MoveCursor(1,1,0);
VideoWriterString("Press a key to hide the cursor",1,1);
GET_KEY();
HideCursor();
VideoWriterString("Press a key to change cursor to a block",2,1);
GET_KEY();
BlockCursor();
VideoWriterString("Press a key to change cursor to a thin cursor",3,1);
GET_KEY();
ThinCursor();
}
There are no return values for HideCursor(), BlockCursor(), or ThinCursor().
Page 276 The C Window Library Page 276
GETTING VIDEO INFORMATION
-------------------------
You can get information about the video configuration by calling the
GetVideoBiosInfo() function.
VIDEO_CONFIG structure
----------------------
To get information about the video configuration, you must pass a pointer
to a VIDEO_CONFIG structure. This structure is defined as follows:
typedef struct
{
unsigned int video_mode; /* Current video mode */
unsigned int cursor_startline; /* Starting scan line of cursor */
unsigned int cursor_endline; /* Ending scan line of cursor */
unsigned int cursor_row; /* Screen row of cursor */
unsigned int cursor_col; /* Column of cursor */
unsigned int video_page; /* Current visible video page */
unsigned int video_pagesize; /* Size in bytes of the video page */
unsigned int video_rows; /* Number of displayable rows */
unsigned int video_cols; /* Number of displayable columns */
unsigned int char_height; /* Height (in scan lines) of a
character */
unsigned int crt_port_address; /* Address of CRT status port */
unsigned int crt_mode_setting; /* Current CRT Mode Setting */
unsigned int crt_color_setting; /* Current CRT color settings */
} VIDEO_CONFIG;
GetVideoBiosInfo()
------------------
This function returns information about the current video configuration.
Here is the prototype:
void GetVideoBiosInfo(VIDEO_CONFIG *v)
The only argument is a pointer to a VIDEO_CONFIG structure. This structure
is filled in with the appropriate values.
Page 277 The C Window Library Page 277
Example:
#include "window.h"
VIDEO_CONFIG v;
main()
{
WindowInitializeSystem();
/* Get video information */
ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white));
GetVideoBiosInfo(&v);
VideoPrintf("The video mode is %d\n"
"The starting scan line of the cursor is %d\n"
"The ending scan line of the cursor is %d \n"
"The row of the cursor is %d \n"
"The column of the cursor is %d\n"
"The video page is %d\n"
"The size of the video page is %d\n"
"The number of rows is %d\n"
"The number of columns is %d\n"
"The height of the characters is %d\n",
v.video_mode, v.cursor_startline, v.cursor_endline,
v.cursor_row,v.cursor_col,
v.video_page, v.video_pagesize, v.video_rows, v.video_cols,
v.char_height);
}
There is no return value for GetVideoBiosInfo().
Page 278 The C Window Library Page 278
TIMED DELAYS
------------
One of the problems that has been addressed in The C Window Library is the
lack of a delay() function in most C compiler packages. The delay() function
delays program execution for a certain number of milliseconds. Borland's
Turbo C compiler is one of the few that has a delay() function. The other
compilers may have a sleep() function, but usually these functions do not
have millisecond accuracy.
One of the problems was to write a delay() function that would work for all
the major C compilers, work with millisecond accuracy, work for any speed
PC, and last but not least, without using floating point arithmetic. This
function was written in assembly language for accuracy. The use of the
delay() is used extensively in displaying and hiding windows with certain
special effects.
delay()
-------
The delay() function delays the program for a certain number of milliseconds.
Here is the prototype:
void delay(unsigned millisecs)
The only argument is the number of milliseconds to delay. If you are using
the Turbo C version of The C Window Library, this function is already
included in the Turbo C library. However, if you are using another compiler
you now have a delay() function!
Example:
main()
{
WindowInitializeSystem();
delay(50); /* Delay for 50 milliseconds */
}
You must call WindowInitializeSystem() before using delay().
There is no return value for delay().
Page 279 The C Window Library Page 279
SOUND FUNCTIONS
---------------
The C Window Library also supports sound functions for compilers that are
lacking these functions.
sound() and nosound()
---------------------
The sound() function sounds a tone with a specified frequency in Hertz
(cycles per second). Here is a prototype:
void sound(unsigned frequency)
The nosound() function turns off the tone generated by the sound() function.
Example:
#include "window.h"
main()
{
unsigned i;
WindowInitializeSystem();
for (i=100;i<=1000;i++)
sound(i);
for(i=1000;i>=100;i--)
sound(i);
nosound();
}
Note for Turbo users:
You should include "dos.h" in your files that contain sound() and nosound().
All other compilers should include "window.h".
Note for Power C users:
If you are using the Power C compiler, you must include "window.h" or any
file that includes window.h after bios.h. This is to ensure that the linker
does not get confused with the Power C function called sound(), which works
differently than the sound() function defined above.
MakeSound()
-----------
The MakeSound() function sounds a tone for a duration of time. Here is the
prototype:
void MakeSound(unsigned freq, unsigned millisec)
Page 280 The C Window Library Page 280
where freq, is the frequency of the tone (in Hertz) and millisec is the
number of milliseconds to sound the tone.
Example:
--------
#include "window.h"
main()
{
WindowInitializeSystem();
/* Produce a 440 Hertz tone for 3 seconds */
MakeSound(440,3000);
}
There is no error return for this function.
Page 281 The C Window Library Page 281
ERROR HANDLING
--------------
Whenever an error has occurred in The C Window Library, a user defined error
function can be called.
The window_error_func function pointer
--------------------------------------
The window_error_func function pointer can point to an error function that
is performed whenever there is an error encountered in one of The C Window
Library functions. If the global variable check_existence_flag is set to 1
and there is an error, The C Window Library will automatically call
window_error_func. Here is the prototype:
void (*window_error_func)(int errcode, char *sourcefile, int sourceline,
char *funcname)
The errcode is one of the defined error codes included in The C Window
Library. Refer to page 6 of the main documentation for more information of
the error codes and their definitions. The second argument is the name of
the file where the error occurred. Only users with the source code to The
C Window Library will have access to this file. The third argument is the
offending line in the source file of where the error occurred. The last
argument is the name of the function of where the error occurred.
By default window_error_func points to a void null function (VOIDNULLFN),
therefore no error function is called.
Here is an example of how to implement automatic error checking:
#include "window.h"
#define WHITEONRED CREATE_VIDEO_ATTRIBUTE(red,white)
void custom_error_func(int, char *, int, char *);
WPOINTER w, error_window;
void initialize_error();
main()
{
WindowInitializeSystem();
WindowSaveInitial(0);
window_error_func = custom_error_func; /* Assign error function */
initialize_error();
WindowOpen(w); /* will be flagged for an error */
}
void initialize_error() /* Initialize error window and error handler */
{
error_window =
WindowInitialize(BORDER,1,1,60,5,WHITEONRED,WHITEONRED,SINGLEBOX);
WindowOpen(error_window);
}
Page 282 The C Window Library Page 282
void custom_error_func(int errcode, char *sourcefile, int sourceline,
char *funcname)
{
int ch;
MakeSound(100,500); /* Produce an error beep */
if (errcode == NO_HEAP_MEM) /* Always check for the heap memory error
separately */
{
VideoWriteString("You have ran out of Heap Memory",1,1);
VideoWriteString(
"Press 'Q' to quit program, Any other key to Continue...",2,1);
}
else /* Display error window */
{
WindowClear(error_window);
WindowDisplay(error_window,1,EXPLODE);
WindowPrintf(error_window,
"Error Code: %d\nSource File: %s\nSource Line %d\nError Occurred in %s",
errcode,sourcefile,sourceline,funcname);
WindowWriteString(error_window,
"Press 'Q' to quit program, Any other key to Continue...",5,1);
}
ch = GET_KEY();
if (ch == 'Q' || ch == 'q')
exit(0);
else
if (errcode != NO_HEAP_MEM)
WindowHide(error_window,CONTRACT);
}
The above example initializes an error window and sets the window_error_func
function pointer to point to the function custom_error_func(). Whenever an
error occurs in The C Window Library, custom_error_func() will be called.
Please note the check to see if the NO_HEAP_MEM error has occurred. It is
important that you check for this error condition separately. The reason for
this is that if there is not enough heap memory, you may inadvertently call a
function in your error handler that calls on malloc() or any of the other
memory allocation related functions. This will either freeze your system,
or more peculiarly, cause your error handler to be called in an infinite
loop because of the repeated failing calls to malloc() or its related
functions. In the latter case, you will run out of stack space.
If you want to unassign the window_error_code function pointer, use the
following line in your code:
window_error_func = VOIDNULLFN;
Page 283 The C Window Library Page 283
USING A MOUSE WITH THE C WINDOW LIBRARY
---------------------------------------
With The C Window Library, you can create applications that use a Microsoft
compatible mouse to select from popup, pulldown, and bar menus.
Installing the Mouse Library
----------------------------
Before using the mouse library, make sure that you read the README file
concerning installing the mouse library.
Include files
-------------
The only include file needed is cwlmouse.h. This file also includes
window.h.
Initializing the Mouse with MouseInitializeSystem()
---------------------------------------------------
Before you can use a mouse, you must initialize it by calling
MouseInitializeSystem(). This function tests for a Microsoft compatible
mouse and returns a value denoting whether a mouse is found. Here is the
prototype:
int MouseInitializeSystem(int intype, int *button, int hpos, int vpos)
The first argument informs MouseInitializeSystem() to whether you just want
to test to see if a mouse is installed and not to activate the mouse, or to
not only test for the mouse, but to activate it. If the first argument is
MOUSE_TEST, MouseInitializeSystem() will just return an integer denoting
whether a mouse is found. If the first argument is MOUSE_FULL_INSTALL, not
only is a status returned, but the mouse will be activated.
The second argument is a pointer to an integer that will contain the number
of buttons that the mouse has. This number will usually be 2 or 3.
The third and fourth arguments are the screen coordinates of where to place
the mouse cursor on the screen. The third argument is the row, and the
fourth argument is the column to place the mouse cursor.
MouseInitializeSystem() returns NOMOUSE if a mouse is not installed, or
MOUSEFOUND if a mouse is installed.
MouseInitializeSystem() must be called after calling WindowInitializeSystem()
for it to work properly.
Page 284 The C Window Library Page 284
Turning off the mouse with MouseRestoreSystem()
-----------------------------------------------
Before terminating a program that has called MouseInitializeSystem() you
should call MouseRestoreSystem(). This function returns the state of the
mouse before calling MouseInitializeSystem(). If you do not call
MouseRestoreSystem(), the mouse will still be 'alive', even though the
application has terminated. Here is the prototype:
int MouseRestoreSystem(void)
If the mouse was not initialized previously with MouseInitializeSystem(),
MouseRestoreSystem() returns NOMOUSE, otherwise the return value is NO_ERROR.
Example:
#include "cwlmouse.h"
main()
{
/* initialize mouse */
MouseInitializeSystem();
/* ... */
/* turn off mouse */
MouseRestoreSystem();
}
If you want to turn the mouse back on after calling MouseRestoreSystem(), you
must call MouseInitializeSystem() again.
Page 285 The C Window Library Page 285
Example:
#include "cwlmouse.h"
main()
{
int button;
int ismouse;
WindowInitializeSystem();
ismouse = (MouseInitializeSystem(MOUSE_FULL_INSTALL,
&button,1,1) == MOUSEFOUND));
MoveCursor(1,1,0);
if (ismouse)
VideoPrintf("Mouse was found. Number of buttons is %d\n",button);
else
VideoPrintf("Mouse not found");
}
Using a mouse with popup menus
------------------------------
Once the mouse is initialized, you can use the mouse to make selections with
popup menus.
To move the highlight bar with the mouse, position the mouse cursor over any
menu entry in the window, and hold the left mouse button down. If the mouse
is moved while holding the left button down, the highlight is moved along
with the mouse cursor. A selection is made by releasing the left mouse
button while the mouse cursor is on an active menu entry.
You can also scroll through the menu entries by placing the mouse on either a
down arrow or up arrow symbols on the popup menu window, and then holding the
left mouse button down. By default, the symbols appear at the bottom border
of the window. If the popup window is borderless, the POPUPMOUSESCROLL
option is ignored.
To activate the mouse so that it can be used for popup menus, you must set
the popup option POPUPMOUSE on. If you also want to use the scroll through
option described above, POPUPMOUSESCROLL should also be turned on.
Page 286 The C Window Library Page 286
Example:
#include "menu.h"
#include "cwlmouse.h"
int menu_func();
POPUP_MENU_ENTRY menu_items[] = {
" Load F3",1,'L',F3,menu_func,
" Pick Alt-F3",2,'P',ALTF3,menu_func,
" New" ,3,'N',0,menu_func,
" Save F2",4,'S',F2,menu_func,
" Write to ",5,'W',0,menu_func,
" Directory ",6,'D',0,menu_func,
" Change Dir" ,7,'C',0,menu_func,
" OS shell" ,8,'O',0,menu_func,
" Quit Alt-X" ,9,'Q',ALTX,menu_func,
CWL_NULL,0};
unsigned int menu_colors[5];
POPUP_MENU_PTR p;
main()
{
int b;
WindowInitializeSystem();
WindowSaveInitial(0); /* Remember to save the initial screen */
MouseInitiailizeSystem(MOUSE_FULL_INSTALL,&b,1,1);
/* define colors */
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a POPUP_MENU_PTR */
p = PopupCreateMenu(menu_items,menu_colors, 1,1,6,
POPUPSTATIC | POPUPMOUSE | POPUPMOUSESCROLL,
WNULLFN,VWNULLFN);
PopupSelectMenu(p, /* POPUP_MENU_PTR */
1, /* rank of popup window */
1 /* menu entry to start on */
);
MouseRestoreSystem();
}
int menu_func(POPUP_MENU_PTR p, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX);
WindowOpen(w);
WindowClear(w);
Page 287 The C Window Library Page 287
WindowPrintf(w,"You have selected %s",POPUP_ENTRY_STRING(p,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return POPUP_EXIT;
else
return POPUP_CONTINUE;
}
The above example uses the popup menu option POPUPMOUSE and POPUPMOUSESCROLL
options in the PopupCreateMenu() function. Also note the call to
MouseInitializeSystem() to initialize the mouse system. You must use the
constant MOUSE_FULL_INSTALL in the MouseInitializeSystem() function to make
sure that the POPUPMOUSE and the POPUPMOUSESCROLL options will take effect.
If a mouse does not exist, or the mouse is not activated, POPUPMOUSE and
POPUPMOUSESCROLL will be ignored. Also note that the include file cwlmouse.h
was included. These are the only changes needed for mouse support for the
popup menus.
Using a mouse with bar menus
----------------------------
To move the highlight bar with the mouse, position the mouse cursor over any
menu entry in the window, and hold the left mouse button down. If the mouse
is moved while holding the left button down, the highlight is moved along
with the mouse cursor. A selection is made by releasing the left mouse
button while the mouse cursor is on an active menu entry.
To activate the mouse so that it can be used for bar menus, you must set the
bar menu option BARMOUSE on.
Example:
#include "menu.h"
#include "cwlmouse.h"
int menu_func();
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',ALTF,menu_func,
"Edit",1,10,'E',0,menu_func,
"Run",1,17,'R',0,menu_func,
"Compile",1,23,'C',0,menu_func,
"Project",1,33,'P',0,menu_func,
"Options", 1,43,'O',0,menu_func,
"Debug",1,53,'D',0,menu_func,
"Break/watch",1,61,'B',0,menu_func,
CWL_NULL};
Page 288 The C Window Library Page 288
unsigned int menu_colors[5];
BAR_MENU_PTR b;
main()
{
int b;
WindowInitializeSystem();
WindowSaveInitial(0); /* Remember to save the initial screen */
MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,1,1); /* Activate mouse */
menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black);
/* create a BAR_MENU_PTR */
b = BarCreateMenu(bar_items,menu_colors, 1,1,
BARSTATIC | BARWRAP | BARMOUSE,WNULLFN);
BarSelectMenu(b,1,1);
MouseRestoreSystem();
}
int menu_func(BAR_MENU_PTR b, unsigned which)
{
WPOINTER w;
w = WindowInitialize(BORDER,15,15,40,4,CREATE_VIDEO_ATTRIBUTE(black,white),
CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX);
WindowOpen(w);
WindowPrintf(w,"You have selected %s",BAR_ENTRY_STRING(b,which));
WindowWriteCenterString(w,"Press a key to continue",3);
WindowDisplay(w,1,NOEFFECT);
GET_KEY();
WindowFree(w,NOEFFECT);
if (which == 9)
return BAR_EXIT;
else return BAR_CONTINUE;
}
The above example uses the bar menu option BARMOUSE option in the
BarCreateMenu() function. Also note the call to MouseInitializeSystem() to
initialize the mouse system. You must use the constant MOUSE_FULL_INSTALL in
the MouseInitializeSystem() function to make sure that the BARMOUSE option
will take effect. If a mouse does not exist, or the mouse is not activated,
BARMOUSE will be ignored. Also note that the include file cwlmouse.h was
included. These are the only changes needed for mouse support for the bar
menus.
Using a mouse with pulldown menus
---------------------------------
If the menu options for the mouse are turned on for all popup menus and the
bar menu, and these menus are used as part of a pulldown menu system, the
mouse behaves exactly the same except for the following differences:
Page 289 The C Window Library Page 289
a) Holding the left mouse button down and positioning the mouse cursor over
a bar menu entry will bring up the popup menu that is associated with
the bar entry. If there is no popup menu defined for a particular bar
entry, releasing the mouse button will invoke the entry's function.
b) Releasing the mouse button when it is positioned over a bar entry, and
the bar entry has a popup associated with it, does nothing. A general
rule is that a menu function is only executed when the highlight bar is
positioned on a menu entry that has a function associated with it.
Here is a full example:
#include "menu.h"
#include "cwlmouse.h"
#define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black)
int menu_routine();
POPUP_MENU_ENTRY menu_items1[] = {
" Load F3",1,'L',F3,menu_routine,
" Pick Alt-F3",2, 'P',ALTF3,menu_routine,
" New" ,3, 'N',0,menu_routine,
" Save F2",4, 'S',F2,menu_routine,
" Write to ",5, 'W',0,menu_routine,
" Directory ",6, 'D',0,menu_routine,
" Change Dir" ,7, 'C',0,menu_routine,
" OS shell" ,8, 'O',0,menu_routine,
" Quit Alt-X" ,9,'Q',ALTX,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items3[] = {
" Run Ctrl-F9 ",1,'R',CTRLF9,menu_routine,
" Program reset Ctrl-F2 ",2,'P',CTRLF2,menu_routine,
" Go to Cursor F4 ",3,'G',F4,menu_routine,
" Trace into F7 ",4,'T',F7,menu_routine,
" Step over F8 ",5,'S',F8,menu_routine,
" User screen Alt-F5 ",6,'U',ALTF5,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items4[] = {
" Compile to OBJ ",1,'C',0,menu_routine,
" Make EXE file ",2,'M',0,menu_routine,
" Link EXE file ",3,'L',0,menu_routine,
" Build all ",4,'B',0,menu_routine,
" Primary C file: ",5,'P',0,menu_routine,
" Get info ",6,'G',0,menu_routine,
CWL_NULL,0};
Page 290 The C Window Library Page 290
POPUP_MENU_ENTRY menu_items5[] = {
" Project Name ",1,'P',0,menu_routine,
" Break make on ",2,'B',0,menu_routine,
" Auto dependencies ",3,'A',0,menu_routine,
" Clear project ",4,'C',0,menu_routine,
" Remove messages ",5,'R',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items6[] = {
" Compiler ",1,'C',0,menu_routine,
" Linker ",2,'L',0,menu_routine,
" Environment ",3,'E',0,menu_routine,
" Directories ",4,'D',0,menu_routine,
" Arguments ",5,'A',0,menu_routine,
" Save Options ",6,'S',0,menu_routine,
" Retrieve options ",7,'R',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items7[] = {
" Evaluate Ctrl-F4 ",1,'E',CTRLF4,menu_routine,
" Call Stack Ctrl-F3 ",2,'C',CTRLF3,menu_routine,
" Find Function ",3,'F',0,menu_routine,
" Refresh display ",4,'R',0,menu_routine,
" Display swapping Smart ",5,'D',0,menu_routine,
" Source debugging ",6,'S',0,menu_routine,
CWL_NULL,0};
POPUP_MENU_ENTRY menu_items8[] = {
" Add watch Ctrl-F7 ",1,'A',CTRLF7,menu_routine,
" Delete watch ",2,'D',0,menu_routine,
" Edit Watch ",3,'E',0,menu_routine,
" Remove all watches ",4,'R',0,menu_routine,
" Toggle breakpoint Ctrl-F8 ",6,'T',CTRLF8,menu_routine,
" Clear all breakpoints ",7,'C',0,menu_routine,
" View next breakpoint ",8,'V',0,menu_routine,
CWL_NULL,0};
BAR_MENU_ENTRY bar_items[] = {
"File",1,4,'F',0,NULLFN,
"Edit",1,10,'E',0,menu_routine,
"Run",1,17,'R',0,NULLFN,
"Compile",1,23,'C',0,NULLFN,
"Project",1,33,'P',0,NULLFN,
"Options", 1,43,'O',0,NULLFN,
"Debug",1,53,'D',0,NULLFN,
"Break/watch",1,61,'B',0,NULLFN,
CWL_NULL};
Page 291 The C Window Library Page 291
POPUP_MENU_ENTRY *pentry[] = {menu_items1, POPUP_NULL_ENTRY,
menu_items3,
menu_items4, menu_items5, menu_items6,
menu_items7, menu_items8};
unsigned menu_colors[5]; /* Menu colors */
BAR_MENU_PTR bar; /* Pointer to bar menu */
POPUP_MENU_PTR popups[8]; /* Array of pointers to popup menus */
PULLDOWN_MENU_PTR pull; /* Pointer to pulldown menu */
WPOINTER my_open(); /* Pointer to custom bar window open function */
unsigned int popuprank[] = {1,1,1,1,1,1,1,1}; /* Ranks of popup windows */
int popupstart[] = {1,1,1,1,1,1,1,1}; /* Starting option for each popup
menu */
int height[] = {9,0,6,6,5,7,6,8}; /* height of each window */
WPOINTER pw; /* Misc. windows, not part of menu
system */
char *line =
"─────────────────────────────"; /* Horizontal line */
main()
{
int i;
WindowInitializeSystem();
WindowSaveInitial(0);
MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,1,1); /* Initialize mouse */
pw = WindowInitialize(BORDER,5,10,70,5,BLACKONWHITE,BLACKONWHITE,
SINGLEBOX);
WindowOpen(pw);
/* define colors */
menu_colors[0] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[1] = CREATE_VIDEO_ATTRIBUTE(white,black);
menu_colors[2] = CREATE_VIDEO_ATTRIBUTE(white,blue);
menu_colors[3] = CREATE_VIDEO_ATTRIBUTE(cyan,black);
menu_colors[4] = CREATE_VIDEO_ATTRIBUTE(white,black);
bar = BarCreateMenu(bar_items, /* Array of BAR_MENU_ENTRY's */
menu_colors,/* Pointer to menu colors */
6, /* Row to open bar menu window */
1, /* Column to open bar menu window */
BARWRAP | BARSTATIC | BARMOUSE,
my_open); /* Customized window open function */
/* Now loop to create all popup menus
Be careful and assign NULL to the second popup menu */
Page 292 The C Window Library Page 292
for (i=0; i<8; i++) /* Loop for all popup menus */
{
if (pentry[i] != POPUP_NULL_ENTRY) /* Skip over NULL popup entry */
{
popups[i] =
PopupCreateMenu(pentry[i], /* Array of POPUP_MENU_ENTRY's */
menu_colors, /* Array of menu colors, */
/* The next two arguments will later be ignored */
1, /* Row to open popup window on */
1, /* Column to open popup */
height[i], /* height of the popup window */
/* No custom window open
functions */
POPUPWRAP | POPUPSTATIC | POPUPMOUSE,
WNULLFN,
VWNULLFN);
/* Now set the popup menu options */
}
else
popups[i] = (POPUP_MENU_PTR)0; /* Make this a null POPUP_MENU_PTR */
} /* end for (i=0 ... */
VirtualWriteString(POPUP_VIRTUAL_WINDOW(popups[7]),line,5,1);
PopupMakeEntryUnavailable(popups[6],2); /* hide 2nd and 3rd entries in */
PopupMakeEntryUnavailable(popups[6],3); /* popups[6] */
PopupSetOptions(popups[6],POPUPOVERRIDE,1);
pull = PulldownCreateMenu(popups,bar,1);
PulldownSelectMenu(pull,1,1,popuprank,popupstart,1);
PulldownMenuFree(pull);
MouseRestoreSystem();
}
int menu_routine(PULLDOWN_MENU_PTR p, BAR_MENU_PTR b,
POPUP_MENU_PTR pop,
unsigned int hs, unsigned int vs)
{
int ch;
WindowClear(pw);
WindowPrintf(pw,
"You have selected bar option %s\npopup option %s\n",
BAR_ENTRY_STRING(b,hs),POPUP_ENTRY_STRING(pop,vs));
WindowWriteCenterString(pw,"Press Escape to Quit",3);
WindowWriteCenterString(pw,"Press any other key to continue...",4);
WindowDisplay(pw,1,NOEFFECT);
ch = GET_KEY();
WindowHide(pw,NOEFFECT);
if (ch == ESC)
return PULLDOWN_EXIT;
return PULLDOWN_CONTINUE;
}
Page 293 The C Window Library Page 293
WPOINTER my_open() /* Custom window open function for bar menu */
{
WPOINTER w;
w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE,BLACKONWHITE,"");
WindowOpen(w);
return w;
}
Changing the mouse defaults
---------------------------
By default, the left mouse button is held down when moving the highlight bar.
If you prefer a different button to be used to move the highlight bar, you
can change the button by changing the following global variables:
int popmenu_button_press - holds the current button to be used to move
the highlight bar in popup menus.
int barmenu_button_press - holds the current button to be used to move
the highlight bar in bar menus.
The following constants can be assigned to these two global variables:
Constant Definition
-------- ----------
MOUSELEFT_PRESS Left button.
MOUSERIGHT_PRESS Right button.
MOUSEMIDDLE_PRESS Middle button.
By default, popmenu_button_press and barmenu_button_press are assigned
MOUSELEFT_PRESS. Here is an example of changing these variables:
#include "cwlmouse.h"
#include "menu.h"
main()
{
...
MouseInitializeSystem( /* arguments */ );
/* change mouse menu buttons */
popmenu_button_press = MOUSERIGHT_PRESS;
barmenu_button_press = MOUSERIGHT_PRESS;
...
}
The popmenu_button_press and barmenu_button_press variables are assigned
their default values when MouseInitializeSystem() is called. If you want to
change these variables, make sure that the change is made after calling
MouseInitializeSystem().
Page 294 The C Window Library Page 294
WINDOW AND VIRTUAL WINDOW MACROS
--------------------------------
Note : These macros should be used after making a call to
WindowInitializeSystem() or else unpredictable values will be returned.
The following macros are defined in the window.h file.
The window w is NOT CHECKED for validity.
ISBORDER(w) - Returns 1 if window has a border, 0 otherwise.
ISWRAP(w) - Returns 1 if window wrap is on, 0 otherwise.
ISOPEN(w) - Returns 1 if window has been opened for read/write, 0
otherwise.
ISVISIBLE(w) - Returns 1 if window is visible, 0 otherwise.
ISVIEWPORT(w) - Returns 1 if window is a viewport, 0 otherwise.
ISWINDOW(vw) - Returns 1 if virtual window has any viewports, 0 otherwise.
ISBUFSAVE(w) - Returns 1 if text buffer for window was successfully,
allocated, 0 otherwise.
ISSEETHRU(w) - Returns 1 if window is in see-thru mode, 0 otherwise.
ISFROZEN(w) - Returns 1 if window is frozen from doing screen updates when
the virtual window has changed, 0 otherwise.
ISSHADOW(w) - Returns 1 if the window has a shadow, 0 otherwise.
ISSHADOWTRANS(w) - Returns 1 if the shadow is transparent, 0 otherwise.
SHADOW_POS(w) - Returns the position of the shadow as an integer. The valid
positions are as follows:
Shadow Position Return Value
--------------- ------------
SHADOWUPLEFT 1
SHADOWUPRIGHT 2
SHADOWLOWLEFT 3
SHADOWLOWRIGHT 4
If there is no shadow, a 0 is returned.
SHADOW_CHAR(w) - Returns the current character used to draw the window's
shadow. Return value is undefined if the window has no
shadow.
Page 295 The C Window Library Page 295
SHADOW_ATTR(w) - Returns the current video attribute used to draw the
window's shadow. Return value is undefined if the window
has no shadow
SHADOW_WIDTH(w) - Returns the width of the window's shadow. Return value is
undefined if the window has no shadow.
SHADOW_HEIGHT(w) - Returns the height of the window's shadow. Return value is
undefined if the window has no shadow.
VIRTUAL_ATTRIBUTE_ON(vw) - Returns 1 if the virtual window vw is attributed,
0 otherwise.
VIRTUAL_WINDOW_EXIST(vw) - Returns 1 if virtual window was
initialized, 0 otherwise.
VIRTUAL_HEIGHT(vw) - Returns the number of rows in a virtual window vw.
VIRTUAL_WIDTH(vw) - Returns the number of columns in a virtual window.
VIRTUAL_WINDOW(w) - Returns the virtual window that the viewport w is currently
viewing.
VIEWPORT_ROW(w) - Returns the upper left row of where the viewport w is
positioned on the virtual window.
VIEWPORT_COLUMN(w) - Returns the upper left column of where the viewport w is
positioned on the virtual window.
VIRTUAL_COORD_IN_VIEWPORT(w,row,col) - Returns 1 if the virtual window
coordinates (row,col) are inside the
viewport w, 0 otherwise. The virtual
window must have w as a viewport.
WINDOW_BORDER_CHARS(w) - Returns the current border of a window as a string.
WINDOW_BORDER_COLOR(w) - Returns the border color of the window w.
WINDOW_COLUMN(w) - Returns the absolute column of the upper left hand corner
of the window.
WINDOW_EXIST(w) - Returns 1 if window was initialized, 0 otherwise.
WINDOW_HEIGHT(w) - Returns the height of the text area of the window w.
WINDOW_PAGENUM(w) - Returns the video page of where the window will be
displayed.
Page 296 The C Window Library Page 296
WINDOW_RANK(w) - Returns the rank of the window w.
WINDOW_ROW(w) - Returns the absolute row coordinate of the upper left hand
corner of the window w.
Page 297 The C Window Library Page 297
MENU MACROS
-----------
The following macros are defined in the header file menu.h.
Popup Menu Macros
-----------------
POPUP_CONFIRM_ON(p) - Returns 1 if the POPUP_MENU_PTR p has the confirmation
for hotkey selections on, 0 otherwise.
POPUP_DISPLAY_ON(p) - Returns 1 if the POPUP_MENU_PTR p's window is to be
displayed regardless if the menu manager has returned
to the calling function, 0 otherwise.
POPUP_ENHANCED_ON(p) - Returns 1 if the popup menu will recognize enhanced
keys, 0 otherwise.
POPUP_ENTRY_STRING(p,entry) - Returns the entry string of POPUP_MENU_ENTRY
entry.
POPUP_EXPLODE(p) - Returns the special effect constant of the
POPUP_MENU_PTR p. This special effect is used to hide,
close, and open the popup menu's window.
POPUP_MOUSE_ON(p) - Returns 1 if a mouse can be used to make selections, 0
otherwise.
POPUP_MOUSE_SCROLL_ON(p) - Returns 1 if a mouse can be used to scroll through
the entries if the entries cannot fit in the popup
window, 0 otherwise.
POPUP_NUMBER_OF_ENTRIES(p) - Returns the total number of entries defined in
the POPUP_MENU_PTR p.
POPUP_OVERRIDE_ON(p) - Returns 1 if POPUP_MENU_PTR p will have unavailable
options processed, 0 otherwise.
POPUP_PULLDOWN_ON(p) - Returns 1 if the POPUP_MENU_PTR p is incorporated in a
pulldown menu system, 0 otherwise.
POPUP_STATIC_ON(p) - Returns 1 if the POPUP_MENU_PTR p will remain on the
screen when an entry is selected, 0 otherwise.
POPUP_STRING_IN_WINDOW(p,entry) - Returns 1 if the POPUP_MENU_PTR p has entry
number entry displayed in the popup menu's
window, 0 otherwise. This macro is useful
if you have a scrolling popup menu and want
to know if a particular entry is displayed
in the window.
POPUP_VIRTUAL_WINDOW(p) - Returns the VWPOINTER of the popup menu.
Page 298 The C Window Library Page 298
POPUP_WINDOW(p) - Returns the WPOINTER of the popup menu.
POPUP_WRAP_ON(p) - Returns 1 if the highlight wrap of POPUP_MENU_PTR p is
on, otherwise 0.
Bar Menu Macros
---------------
BAR_CONFIRM_ON(b) - Returns 1 if the BAR_MENU_PTR b has the confirmation for
hotkey selections on, 0 otherwise.
BAR_DISPLAY_ON(b) - Returns 1 if the BAR_MENU_PTR b's window is to be
displayed regardless if the menu manager has returned to
the calling function, 0 otherwise.
BAR_ENHANCED_ON(p) - Returns 1 if the bar menu will recognize enhanced keys,
0 otherwise.
BAR_ENTRY_AVAILABLE(b,entry) - Returns 1 if the BAR_MENU_ENTRY entry is
available, 0 otherwise.
BAR_ENTRY_STRING(b,entry) - Returns the entry string of BAR_MENU_ENTRY entry.
BAR_EXPLODE(b) - Returns the special effect constant of the BAR_MENU_PTR b.
This special effect is used to hide, close, and open the
popup menu's window.
BAR_NUMBER_OF_ENTRIES(b) - Returns the total number of entries defined in
the BAR_MENU_PTR b.
BAR_OVERRIDE_ON(b) - Returns 1 if BAR_MENU_PTR b will have unavailable
options processed, 0 otherwise.
BAR_PULLDOWN_ON(b) - Returns 1 if the BAR_MENU_PTR b is incorporated in a
pulldown menu system, 0 otherwise.
BAR_STATIC_ON(b) - Returns 1 if the BAR_MENU_PTR b will remain on the screen
when an entry is selected, 0 otherwise.
BAR_WINDOW(b) - Returns the WPOINTER of the bar menu.
BAR_WRAP_ON(b) - Returns 1 if the highlight wrap of BAR_MENU_PTR b is on,
otherwise 0.
Page 299 The C Window Library Page 299
Pulldown Menu Macros
--------------------
BAR_MENU_PTR_FROM_POPUP(pop) - Returns the BAR_MENU_PTR associated with the
POPUP_MENU_PTR pop, which must be part of a
pulldown menu system.
BAR_MENU_PTR_FROM_PULLDOWN(pull) - Returns the BAR_MENU_PTR assocated with
the PULLDOWN_MENU_PTR pull.
POPUP_MENU_PTR_FROM_BAR(b,entry) -
Returns the POPUP_MENU_PTR associated with the
BAR_MENU_PTR b. The entry argument is the number of the
POPUP_MENU_PTR desired in the pulldown menu system. For
example, if you want to know the first POPUP_MENU_PTR
given only a BAR_MENU_PTR, the call to this macro would
be POPUP_MENU_PTR_FROM_BAR(b,1).
POPUP_MENU_PTR_FROM_PULLDOWN(pull,entry) -
Returns the POPUP_MENU_PTR associated with the
PULLDOWN_MENU_PTR pull. The entry is the number of the
desired POPUP_MENU_PTR desired in the pulldown menu
system.
PULLDOWN_MENU_PTR_FROM_BAR(b) - Returns the PULLDOWN_MENU_PTR associated with
the bar menu b.
PULLDOWN_MENU_PTR_FROM_POPUP(pop) - Returns the PULLDOWN_MENU_PTR associated
with the POPUP_MENU_PTR pop.
Page 300 The C Window Library Page 300
VIDEO MACROS
------------
The following macros are defined in the vidsys.h file.
Note: by including window.h in your source files, vidsys.h is automatically
included.
CHECK_SNOW - Returns 1 if during direct screen writes that video "snow" is
eliminated. You can also assign values to this macro. This
macro is a pseudonym for the variable chksnow_.
Example:
#include "vidsys.h"
...
int a;
a = CHECK_SNOW; /* Returns 1 if snow checking on,
0 otherwise */
CHECK_SNOW = 0; /* Turn off snow checking */
CREATE_VIDEO_ATTRIBUTE(bg,fg) - creates a video attribute using bg as the
background color, and fg as the foreground color. The
following variables can be used:
Variable | Variable
Name Color Value | Name Color Value
------- ----- ----- | ------- ----- -----
black Black 0 | gray Gray 8
blue Blue 1 | lightblue Light Blue 9
green Green 2 | lightgreen Light green 10
cyan Cyan 3 | lightcyan Light cyan 11
red Red 4 | lightred Light red 12
magenta Magenta 5 | lightmagenta Light magenta 13
brown Brown 6 | yellow Yellow 14
white White 7 | lightwhite Intense white 15
The variables above are initialized when WindowInitializeSystem() is called.
If you want to use a color value before WindowInitializeSystem() is called,
you can use the uppercase equivalent of the above variables, with a trailing
underscore character attached to the name. For example BLACK_ would be used
instead of black, WHITE_ would be used instead of white, etc. For monochrome
systems, the only colors that are available are black, white, and intense
white. An attribute of blue creates an underline attribute, and light blue
creates an intense underlined attribute. Any other combination on a
monochrome system is undefined.
GET_BGROUND_COLOR(c) - Returns the background color of the video attribute c.
GET_FGROUND_COLOR(c) - Returns the foreground color of the video attribute c.
GET_OFFSET(x) - Returns the offset of a pointer x. The pointer can be either
near or far.
Page 301 The C Window Library Page 301
GET_SEGMENT(x) - Returns the segment address of a pointer x. The pointer can
be either near or far.
MAKE_FAR_POINTER(a,b) - Creates a far pointer made up of segment address a,
and offset address b.
SCREEN_OFFSET(r,c,a) - Returns the screen offset of the address of a
character located at row r and column c of the video
page a. The screen segment is defined in the macro
SCREEN_SEGMENT. both r and c should be >= 1.
Example:
char far *p;
p = MAKE_FAR_POINTER(SCREEN_SEGMENT,SCREEN_OFFSET(1,1,0));
The above example has created a far pointer p that points to the
screen buffer memory at row 1, column 1, on video page 0.
SCREEN_OFFSET_ATTR(r,c,a) - Returns the screen offset of the address of a
attribute located at row r and column c of the video page
a. The screen segment is defined in the macro
SCREEN_SEGMENT. both r and c should be >= 1.
SCREEN_SEGMENT - Returns the screen segment of video page 0. This macro is a
pseudonym for the variable scrnseg_.
SCREEN_WRITE_METHOD - Returns 1 if writing directly to the screen, 0 if using
the BIOS. You can also use this macro to assign the
particular writing method. This macro controls the way
The C Window Library will do screen updates. The
default is 1 (write directly to screen).
Example:
#include "vidsys.h"
int a,b;
a = SCREEN_WRITE_METHOD; /* a now has the current write method */
SCREEN_WRITE_METHOD = 1; /* set write method to direct screen
memory */
This macro is a pseudonym for the variable scrnwrt_flag which is a
member of the SYS_FLAGS structure video_system_flags.
VIDEO_PAGESIZE - Returns the size (in bytes) of a video page. You can also
assign values to VIDEO_PAGESIZE, but the best thing to do is
to leave it alone unless you are familiar with the video
system you are using. This macro is a pseudonym for the
variable pagesize_.
Example:
#include "vidsys.h"
int psize;
psize = VIDEO_PAGESIZE; /* Return the current
video page size */
Page 302 The C Window Library Page 302
The following macros are used to identify the monitor type and video card
being used in the system.
Note : These macros are pseudonyms for members in the SYS_FLAGS structure
called video_system_flags.
CGA_ACTIVE - Returns 1 if Color Graphics Adapter is active, 0 otherwise.
EGA_ACTIVE - Returns 1 if EGA is active, 0 otherwise.
EGA_COLOR_ATTACHED - Returns 1 if monitor hooked up to EGA is a high
resolution color monitor, 0 otherwise.
EGA_COLOR_ON - Returns 1 if EGA is in color mode, 0 otherwise.
EGA_INSTALLED - Returns 1 if EGA is installed, 0 otherwise.
HERCULES_ACTIVE - Returns 1 if Hercules adapter is active, 0 otherwise.
MCGA_ACTIVE - Returns 1 if the MCGA is the active video card.
MCGA_COLOR_ON - Returns 1 if MCGA is in color mode, 0 otherwise.
MCGA_INSTALLED - Returns 1 if MCGA is installed (IBM PS/2 Model 30),
0 otherwise.
MDA_ACTIVE - Returns 1 if MDA (Monochrome) adapter is active,
0 otherwise.
MONO_MODE_ON - Returns 1 if Monochrome mode is on regardless of the
adapter, 0 otherwise.
VGA_ACTIVE - Returns 1 if VGA is active adapter, 0 otherwise.
VGA_COLOR_ATTACHED - Returns 1 if monitor hooked up to VGA is analog color,
0 otherwise.
VGA_COLOR_ON - Returns 1 if VGA is in color mode, 0 otherwise.
VGA_INSTALLED - Returns 1 if VGA Adapter is installed, 0 otherwise.
You should always check the ..._ACTIVE constants before checking for other
aspects of the video system. For example, make sure that VGA_ACTIVE returns
1 before checking any other VGA_... macro. If VGA_ACTIVE is 1, then all
VGA_... macros are valid. The same thing goes for EGA. MONO_MODE_ON is the
only macro that can be tested regardless of the video adapter.
The following are macros defined in version 1.0 of The C Window Library,
which are still supported:
CGA_MODE_ON - Same as CGA_ACTIVE.
EGA_MODE_ON - Same as EGA_ACTIVE.
VGA_MODE_ON - Same as VGA_ACTIVE.
MCGA_MODE_ON - Same as MCGA_ACTIVE.
EGA_MONO_ON - Returns 1 if EGA is in mono mode.
VGA_MONO_ON - Returns 1 if VGA is in mono mode.
MCGA_MONO_ON - Returns 1 if MCGA is in mono mode.
You should not assign values to the above pseudo-constants unless you are
completely familiar with The C Window Library's internal functions.
LINEMODE25 - Returns 1 if screen displays 25 lines, 0 otherwise.
LINEMODE43 - Returns 1 if screen displays 43 lines (EGA and VGA), 0
otherwise.
LINEMODE50 - Returns 1 if screen displays 50 lines (VGA), 0 otherwise.
Page 303 The C Window Library Page 303
BOX MACROS
----------
The list of defined box drawing macros is as follows:
DOUBLEBOX
SINGLEBOX
MIXEDBOX1
MIXEDBOX2
HATCHBOX1
HATCHBOX2
HATCHBOX3
SOLIDBOX1
SOLIDBOX2
BLANKBOX
DOTTEDLINE
Each one of these macros are 8 character strings that can be used in
functions that call for a string of box drawing characters.
Page 304 The C Window Library Page 304
EXPLOSION MACROS
----------------
The list of explosion constants is as follows:
NOEFFECT
EXPLODE
CONTRACT
BRICKS
MIDDLEROWOUT
TOPBOTTOMIN
TOPDOWN
BOTTOMUP
MIDDLECOLOUT
LEFTRIGHTIN
LEFTTORIGHT
RIGHTTOLEFT
Page 305 The C Window Library Page 305
KEYBOARD MACROS
---------------
The following macros are used to get characters from the keyboard.
They are prototyped in the file key.h.
ENHANCED_KEYBOARD() - Returns 1 if there is an enhanced keyboard attached, 0
otherwise.
FLUSH_KEYBOARD() - Flushes the keyboard buffer.
GET_KEY() - Returns what key was pressed either as a character, or as a
scan code if a non-ascii key is pressed. A list of scan codes are
found in the file keycodes.h.
GET_ENHANCED_KEY() - Same as GET_KEY() except that keys on the enhanced
keyboards are distinguishable. For instance, the key on
the keypad will return a different scan code than the
Home key on the separate cursor movement pad.
GET_SHIFT_STATE() - Returns the shift state of the keyboard. The shift state
tells whether the Alt, Ctrl or Shift key was pressed, or
if the Num Lock, Scroll Lock, or Caps Lock keys are on or
off. The shift state is updated after each call to
GET_KEY() or GET_ENHANCED_KEY(). Use a bitwise AND (&)
when testing for these keys, as the example below
demonstrates:
Example:
#include "key.h"
#include "keycodes.h"
...
int CurrentShift;
GET_KEY();
CurrentShift = GET_SHIFT_STATE() & ALT;
printf("The Alt key was %s pressed",
CurrentShift?"":"not");
ISKEYREADY() - Returns 1 if there is a key ready in the keyboard buffer, 0
otherwise.
Page 306 The C Window Library Page 306
Keyboard Idle function
----------------------
When calling the GET_KEY() or GET_ENHANCED_KEY() macros, you can call a
function while the program is waiting for a key to be pressed. The global
variable key_idle_func is a function pointer that points to this function.
Here is the prototype:
void (*key_idle_func)(void)
There are no arguments and no return value to this function. You must
initialize this function pointer after you have called
WindowInitializeSystem(). If not, the function you assigned will not be
executed. Here is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
void count_numbers(void);
int num = 0;
main()
{
WindowInitializeSystem();
key_idle_func = count_numbers;
ClearScreen(NORM);
GET_KEY();
MoveCursor(2,1,0);
VideoPrintf("You stopped the count at %d",num);
}
void count_numbers()
{
num++;
MoveCursor(1,1,0);
VideoPrintf("%d",num);
delay(1000);
}
The program above keeps a counter going in the upper left hand corner of the
screen until a key is pressed.
If you want to unassign the key_idle_func function pointer, do the
following:
key_idle_func = VOIDNULLFN;
This function can perform just about anything. One major use would be to
update an on screen clock while the keyboard is not being used.
Page 307 The C Window Library Page 307
Keyboard Intercept function
---------------------------
Before GET_KEY() and GET_ENHANCED_KEY() return a value, you can intercept the
pending return value, examine it, and change the value to whatever you wish.
This is good if you want to reassign keys easily. The function pointer to
assign is key_intercept_func. Here is the prototype:
unsigned (*key_intercept_func)(int which, unsigned keyval)
The first argument is an integer that denotes whether a mouse button was
pressed, or a key from the keyboard was pressed. If a keyboard key was
pressed, the value of which is equal to KEYPRESSED, otherwise it is
MOUSEPRESSED. If you do not have a mouse, or the mouse is not activated,
this value will always be KEYPRESSED. More information on the mouse in the
USING THE MOUSE section in the manual. The return value will be the new key
value that GET_KEY() and GET_ENHANCED_KEY() will return. It is advisable to
use the key codes described in "keycodes.h" if you are returning a non-ascii
key. Here is an example:
#include "window.h"
#define NORM CREATE_VIDEO_ATTRIBUTE(black,white)
unsigned switch_to_quotes(int,unsigned);
unsigned oldchar;
main()
{
int ch;
WindowInitializeSystem();
key_intercept_func = switch_to_quotes;
ClearScreen(NORM);
ch = GET_KEY();
MoveCursor(1,1,0);
VideoPrintf("The old key was %c. The new code is %c",oldchar,ch);
}
unsigned switch_to_quotes(int which, unsigned keyval)
{
if (which == KEYPRESSED)
{
oldchar = keyval;
return (unsigned)'"'; /* return a double quote */
}
}
The program above intercepts the return value of GET_KEY() and assigns the
double quote character. The character is then printed out on the screen
along with the character that was assigned.
If you want to unassign the key_intercept_func function pointer, do the
following:
key_intercept_func = NULLFN;
Page 308 The C Window Library Page 308
CURSOR MACROS
-------------
The following macros are used for cursor manipulation.
CREATE_CURSOR_SHAPE(startline, endline) - Forms an integer quantity
representing a cursor with a starting scan line of
scanline, and an ending scan line of endline.
THIN - constant for a thin (underline) cursor.
BLOCK - constant for a block (fat) cursor.
INVISIBLE - constant for a hidden cursor.
Page 309 The C Window Library Page 309
IMPORTANT GLOBAL VARIABLES
--------------------------
There are global variables that you should be aware of in The C Window
Library. Most of these variables can be changed, while others should be left
alone. You must call WindowInitializeSystem() before modifying any of these
variables.
When describing the global variable, the following scheme is used:
Variable variable name
Defined in XXXXXX.h (file where variable is declared)
Initialized in function call (function where variable gets its initial
value)
Purpose Description of variable's purpose.
Default Value default value for variable.
Modify Info Tells if variable should be modified.
These variables are described in alphabetical order.
Variable int active_video_page
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Current active video page.
Modify Info Should be modified only by calling the SetActiveVideoPage()
function.
Page 310 The C Window Library Page 310
Variable int barmenu_button_press
Defined in cwlmouse.h
Initialized in MouseInitializeSystem()
Purpose Holds the current button mouse button to press to move the
highlight bar on bar menus.
Default Value MOUSELEFT_PRESS.
Modify Info Can be modified at any time.
Variable int caldelay_
Defined vidsys.h
Initialized in WindowInitializeSystem()
Purpose This is a calibration count for the delay() function.
Modify Info Should only be modified if the delay() function is giving
inaccurate delay times. If the delay is too long, then
caldelay_ should be decreased. If it is too short, then
caldelay_ should be increased.
Variable int check_existence_flag
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Informs The C Window Library to check for window, virtual
window, and for non-open window errors. If this variable is
1, the library routines will check for these conditions. If
0, these conditions are not checked.
Default Value 1.
Modify Info Can be modified at any time, but is recommended that this
flag be left on for development work. Make sure that your
application program is stable if you plan to turn off
checking.
Page 311 The C Window Library Page 311
Variable int chksnow_
Defined vidsys.h
Initialized in WindowInitializeSystem()
Purpose This variable controls whether the display should be checked
for snow when writing directly to the screen. A value of
1 will check for snow, while a value of 0 will turn off
snow checking.
Default Value 0 (no snow checking).
Modify Info Can be modified at any time.
Variable int crt_status_port
Defined vidsys.h
Initialized in WindowInitializeSystem()
Purpose This variable holds the value of the CRT status port. This
port is used to test when it is safe to read or write
characters to the screen without producing snow.
Modify Info Should not be modified.
Variable int default_cursor_mode
Defined key.h
Initialized in WindowInitializeSystem()
Purpose Holds the mode that the WindowGet...() functions will
operate in when called. The modes are either OVERSTRIKEMODE
or INSERTMODE.
Default Value OVERSTRIKEMODE.
Modify Info Can be modified at any time.
Example:
default_cursor_mode = INSERTMODE;
Page 312 The C Window Library Page 312
Variable int default_cursor_type[2]
Defined key.h
Initialized in WindowInitializeSystem()
Purpose Holds the cursor shapes for OVERSTRIKEMODE and INSERTMODE
input modes.
Default Value default_cursor_type[OVERSTRIKEMODE] is set to a block cursor.
default_cursor_type[INSERTMODE] is set to an underline
cursor.
Modify Info Can be modified at any time.
Example:
default_cursor_type[INSERTMODE] = CREATE_CURSOR_SHAPE(5,7);
Variable int default_screen_attr
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Default video attribute used when any Video...() functions
are called to write to the screen.
Default Value 7 (black background, white foreground).
Modify Info Can be modified at any time.
Variable int enhanced_keyboard
Defined in key.h
Initialized in WindowInitializeSystem()
Purpose Tells if an enhanced keyboard is attached. If
enhanced_keyboard is 1, an enhanced keyboard is active,
otherwise if 0, the keyboard is not an enhanced keyboard.
Modify Info Can be modified safely.
Page 313 The C Window Library Page 313
Variable int explosion_speed[12]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose This array holds the number of milliseconds of delay for
each of the special effects supported in The C Window
Library.
Default Value 10 (10 ms.), except for explosion_speed[BRICKS], which is 1
ms.
Modify Info Can be modified safely at anytime. The way you would modify
the values is to use the special effects constants. For
example:
explosion_speed[CONTRACT] = 5;
The above example changes the explosion delay for the
CONTRACT special effect to 5 ms.
Variable int flush_keyboard_flag.
Defined in key.h
Initialized in WindowInitializeSystem().
Purpose Tells if the keyboard buffer should be flushed whenever
the GET_KEY() or GET_ENHANCED_KEY() macros are called. A
value of 1 means the buffer will be flushed.
Default Value 0 (no flush).
Modify Info Can be modified at any time.
Page 314 The C Window Library Page 314
Variable VIDEO_CONFIG initial_video_startup
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Structure that holds the video configuration when
WindowInitializeSystem() is called.
Modify info Should not be modified if the initial video startup is
desired when exiting an application.
Variable char input_mask_char
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the mask character that is used for input routines.
The character defined in input_mask_char is used in input
masks to specify an input position in the edit field. Refer
to the functions WindowGet..() functions for more
information concerning character masks.
Default Value '_' (0x5F).
Modify Info Can be modified safely at any time, except when in the middle
of a user defined function that was called by The C Window
Library's input routines.
Variable void (*key_idle_func)(void)
Defined in key.h
Initialized in WindowInitializeSystem()
Purpose pointer that points to a function that is performed whenever
the GET_KEY() and GET_ENHANCED_KEY() macros do not have a
key ready to be processed.
Modify Info Can be modified at any time.
Page 315 The C Window Library Page 315
Variable unsigned (*key_intercept_func)(int which, unsigned keyval)
Defined in key.h
Initialized in WindowInitializeSystem()
Purpose pointer that points to a function which traps any keystrokes
that the GET_KEY() and GET_ENHANCED_KEY() macros will
return.
Modify Info Can be modified at any time.
Variable int max_video_pages
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Total number of video pages detected by The C Window Library.
Modify Info Should not be modified unless a modification to the
screen_page_offset array was done.
Variable int max_window_rank
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the rank value of the bottom-most (i.e. the
window that will have all other windows covering it).
Modify Info Do not modify.
Page 316 The C Window Library Page 316
Variable int min_window_rank
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the rank value of the top-most visible window.
Modify Info Do not modify.
Variable int (*num_chars_entered_func)(char *string, int minchars)
Defined in key.h
Arguments string - string that was entered.
minchars - minimum number of characters expected.
Initialized in WindowInitializeSystem()
Purpose Pointer to user-defined function that will be executed when
the input manager detects that there were not enough
characters entered.
Default Value NULLFN.
Variable int (*num_chars_entered_func)(char *string, int minchars)
Defined in key.h
Arguments string - string that was entered.
minchars - minimum number of characters expected.
Initialized in WindowInitializeSystem()
Purpose Pointer to user-defined function that will be executed when
the input manager detects that there were not enough
characters entered.
Default Value NULLFN.
Modify info Can be modified at any time.
Return Values Must return DONT_PROCESS or ACCEPT_INPUT.
Page 317 The C Window Library Page 317
Variable int num_transparent_shadows[16]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Array of the number of transparent shadows that are currently
displayed for each display page.
Default Value 0 for each array element.
Modify Info Do not modify.
Variable WPOINTER orig_screen[16]
Defined in window.h
Initialized in WindowSaveInitial()
Purpose Array of windows created when WindowSaveInitial() is called.
The original screen for video page 0 is orig_screen[0], page
1 is orig_screen[1], etc.
Modify Info You can use any window function on the original screen,
except for ones that resize, move, hide, display, or close.
If you write strings to the original screen, you will
permanently destroy the contents of the original screen at
the positions that have been modified.
Example:
WindowWriteString(orig_screen[0],"123",1,1);
The above example writes "123" to the upper left hand corner
of the original screen of video page 0.
Variable int pagesize_
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the size of a display page in bytes.
Modify Info Should not be modified unless The C Window Library did not
detect the correct video page size.
Page 318 The C Window Library Page 318
Variable int popmenu_button_press
Defined in cwlmouse.h
Initialized in MouseInitializeSystem()
Purpose Holds the current button mouse button to press to move the
highlight bar on popup menus.
Default Value MOUSELEFT_PRESS.
Modify Info Can be modified at any time.
Variable int (*reg_exp_error_func)(char *string, int nomatch);
Defined in key.h
Arguments string - string that was entered.
nomatch - position of the first non-matching character.
Initialized in WindowInitializeSystem()
Purpose Pointer to user-defined function that will be executed when
the input manager detects that there are illegal characters
in the string when it is compared to the regular
expression. This function is only called when it is not
equal to NULLFN, and the CHECKREGEXP option is on.
Default Value NULLFN.
Modify info Can be modified at any time.
Return Values Must return DONT_PROCESS or ACCEPT_INPUT.
Page 319 The C Window Library Page 319
Variable unsigned char *screen_image[16]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Used for internal window management. Each pointer in the
screen_image array points to an image of the current
window organization of the screen. For example
screen_image[0] is a pointer to the current window "layout"
for video page 0.
Modify Info DO NOT modify this. This array is VERY important when window
updates are done.
Variable unsigned char far *screen_page_offset[16]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Array of starting addresses of each video page.
Modify Info You can modify if The C Window Library fails to detect video
pages that your video card may have.
Invalid video pages will set screen_page_offset[page] to a
far NULL pointer, where page is the invalid video page.
If there is a failure to detect video pages that your card
may have, you can use the MAKE_FAR_POINTER macro to
initialize.
Example: screen_page_offset[page] =
MAKE_FAR_POINTER(0xB000,0x2000);
where page is the page to initialize. You should have the
documentation of the video card on hand so that you are sure
of the starting address of the video page.
You must also adjust the global variable max_video_pages to
reflect the new number of pages, and the pagesize_ variable
to reflect the size of each video page.
Page 320 The C Window Library Page 320
Variable int (*undef_akey_func)(char *string, unsigned key, int pos,
int *newpos)
Defined in key.h
Arguments string - string currently entered.
key - key that was hit.
pos - position where cursor is in the input string.
Purpose Pointer to a function that is executed when a key that is not
defined in an input routines regular expression is pressed.
Default Value NULLFN.
Modify Info Can be modified at any time.
Return Values Refer to the manual for more information.
Variable int (*undef_fkey_func)(char *string, unsigned key, int pos,
int *newpos)
Defined in key.h
Arguments string - string currently entered.
key - key that was hit.
pos - position where cursor is in the input string.
Purpose Pointer to a function that is executed when a key that is not
defined in an input routines regular expression is pressed.
Purpose Pointer to a function that is executed when a key that is not
defined in the window_edit_key array is pressed.
Default Value NULLFN.
Modify Info Can be modified at any time.
Return Values Refer to to the main documentation for more information.
Page 321 The C Window Library Page 321
Variable VWPOINTER virtual_window_ptrs[256]
Defined in window.h
Purpose Array of all initialized virtual window pointers.
Modify Info Do not modify.
Variable int visible_video_page
Defined in vidsys.h
Initialized in WindowInitializeSystem()
Purpose Current visible video page.
Modify Info Should be modified only by calling the SetVisibleVideoPage()
function.
Variable unsigned window_edit_key[12]
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Array of edit key definitions. This array is used in the
window input routines.
Modify Info You can modify values in the array, provided that there are
no duplicate definitions, and there is a definition for a key
that terminates user input. Refer to the GETTING INPUT FROM
WINDOWS section.
Page 322 The C Window Library Page 322
Variable int window_error_code
Defined in window.h
Initialized in WindowInitializeSystem()
Purpose Holds the last error that occurred as an integer. You should
always check the value of window_error_code to determine what
has happened if a function fails. All of the window and
virtual window functions return an error status when things
go wrong. However, only selected functions from the Video...
family of functions set window_error_code. The value in
window_error_code corresponds to the values found in
the file werror.h.
window_error_code does not reset itself if there are no
errors.
Default Value 0.
Modify Info Safe to modify, but will always reset itself to an error
condition if a function fails.
Variable WPOINTER window_ptrs[256];
Defined in window.h
Purpose Array of all initialized windows.
Modify Info DO NOT modify.
Variable WPOINTER window_rank[257];
Defined in window.h
Purpose Array of all visible windows in rank order.
Modify Info DO NOT modify.
Page 323 The C Window Library Page 323
Page 324 The C Window Library Page 324